Skippr Docs

Appearance

Scheduler ​

Scheduler runs work at a time you choose: once, on a rate, or on a cron. It delivers a payload to a queue or publishes an event. Use this for hourly reports, delayed retries, and other jobs that should not live in your application process.

Status: Preview. See the API action reference for the full command list.

Create your first schedule ​

Before this command, create the destination event bus or queue, sign in with skippr login, and ensure your policy allows scheduler:CreateSchedule. The same schedule is CLI, Terraform, CDKTF TypeScript, or CDKTF Python. Terraform and CDKTF declare an events target (target_source). Queue targets remain available on the CLI. For provider credentials and the shared cloud provider block, see Terraform and CDKTF.

bash
skippr scheduler create-schedule --input - <<JSON
{
  "name": "hourly-report",
  "scheduleExpression": "rate(1 hours)",
  "state": "ENABLED",
  "target": {
    "source": "app.scheduler",
    "detailType": "report.due",
    "detail": "{\"report\":\"hourly\"}"
  }
}
JSON
hcl
resource "cloud_schedule" "hourly_report" {
  name               = "hourly-report"
  expression         = "rate(1 hours)"
  target_source      = "app.scheduler"
  target_detail_type = "report.due"
  target_detail      = jsonencode({ report = "hourly" })
}
ts
import { CloudProvider, CloudSchedule } from "@skippr/provider-cloud";

const cloud = new CloudProvider(this, "cloud", { region: "eu-central-1" });

new CloudSchedule(this, "hourly-report", {
  name: "hourly-report",
  expression: "rate(1 hours)",
  targetSource: "app.scheduler",
  targetDetailType: "report.due",
  targetDetail: JSON.stringify({ report: "hourly" }),
  provider: cloud,
});
python
import json
from skippr_cdktf import CloudProvider, CloudSchedule

cloud = CloudProvider(self, "cloud", region="eu-central-1")

CloudSchedule(
    self,
    "hourly-report",
    name="hourly-report",
    expression="rate(1 hours)",
    target_source="app.scheduler",
    target_detail_type="report.due",
    target_detail=json.dumps({"report": "hourly"}),
    provider=cloud,
)

The response includes the normalized target, state, and next fireAt.

Timing and target rules ​

All schedule expressions use UTC.

FormExampleBehavior
at()at(2026-08-03T14:30:00)Fires once, then becomes COMPLETED
rate()rate(15 minutes)Repeats in minutes, hours, or days
cron()cron(0 9 * * *)Five fields: minute, hour, day of month, month, day of week

Seconds-based rates are not supported. There is no time-zone field or daylight-saving adjustment; convert local times to UTC before creating the schedule.

Queue target ​

json
{
  "target": {
    "queueName": "report-jobs",
    "messageBody": "{\"report\":\"hourly\"}"
  }
}

Events target ​

json
{
  "target": {
    "source": "app.scheduler",
    "detailType": "report.due",
    "detail": "{\"report\":\"daily\"}"
  }
}

Streams targets are rejected in Preview. A schedule has one target.

Operations by task ​

Create and change timing ​

OperationUse it to
CreateScheduleCreate a named schedule with expression, target, and optional state
UpdateScheduleChange its expression, target, state, or description

Use DISABLED to retain a schedule without firing it. Valid states are ENABLED, DISABLED, and COMPLETED.

Inspect ​

OperationUse it to
GetScheduleRead the full schedule and next fireAt
ListSchedulesList schedule names

Remove ​

OperationUse it to
DeleteSchedulePermanently remove the schedule

Limits and delivery contract ​

ContractValue
Schedules per account1,000
Time zoneUTC only
Cron syntaxFive fields
Rate unitsMinutes, hours, days
TargetsQueue or events
DeliveryAt least once

The scheduler claims a due fire, delivers to queue or events, then records a receipt before advancing the next fire time. Delivery is at least once: a crash during delivery may deliver more than once, so queue consumers and event handlers should be idempotent. Create with immediate: true is due immediately and is delivered by the worker on the next tick, not on the Create response.

Errors ​

Code or statusMeaning
ResourceNotFoundExceptionThe schedule does not exist
InvalidParameterValueInvalid state or schedule expression
ValidationExceptionMissing fields, schedule quota reached, or unsupported target
InternalServerErrorDelivery or service storage failed
401 / 403Missing authentication or a policy denial