Schedules

Cron syntax, timezones, and one-time scheduling.

Schedule types

Every cue has one of two schedule types:

Type	Description	Schedule field
`recurring`	Fires on a cron schedule, repeats indefinitely	`cron`
`once`	Fires once at a specific time, then completes	`at`

Cron syntax

CueAPI uses standard 5-field cron expressions:

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sun=0)
│ │ │ │ │
* * * * *

Examples

Expression	Description
`0 9 * * *`	Every day at 9:00 AM
`0 9 * * 1-5`	Weekdays at 9:00 AM
`/15 * * *`	Every 15 minutes
`0 0 1 * *`	First of every month at midnight
`30 8 * * 1`	Every Monday at 8:30 AM
`0 /6 * *`	Every 6 hours
`0 9,17 * * *`	9 AM and 5 PM daily

Timezones

By default, cron expressions are evaluated in UTC. Specify a timezone to schedule in local time:

json

{
  "schedule": {
    "type": "recurring",
    "cron": "0 9 * * *",
    "timezone": "America/New_York"
  }
}

CueAPI supports all IANA timezone names (e.g., America/Los_Angeles, Europe/London, Asia/Tokyo).

Note

Timezone-aware cron expressions automatically adjust for daylight saving time transitions.

One-time schedules

For a single future event, use an ISO 8601 timestamp:

json

{
  "schedule": {
    "type": "once",
    "at": "2026-03-15T14:00:00Z"
  }
}

The timestamp must be in the future. After the cue fires:

On success → status changes to completed
On failure (retries exhausted) → status changes to failed

How CueAPI calculates next_run

For recurring cues:

On creation → next_run is the next occurrence after now, calculated by croniter
After each fire → next_run advances to the next occurrence
On resume (after pause) → next_run is recalculated from now

For one-time cues:

On creation → next_run is the at timestamp
After fire → next_run is cleared

Cron validation

CueAPI validates cron expressions at creation time using the croniter library. Invalid expressions return 400 invalid_schedule:

json

{
  "error": {
    "code": "invalid_schedule",
    "message": "Invalid cron expression: '* * * *'",
    "status": 400
  }
}

Previous← Transport NextPayloads →