Schedules and timezones

A schedule is a five-field cron expression plus an IANA timezone. The scheduler computes the next occurrence in that zone, and the operations tick claims routines whose occurrence has passed.

Cron format

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

Five fields are required. Six-field (seconds) and @daily-style shorthand are not accepted.

An expression that cannot produce a future occurrence is rejected with 400 invalid_schedule.

Timezones

The timezone is an IANA identifier such as America/Los_Angeles or Europe/Berlin. The picker lists every zone your browser knows, grouped by region and labelled with its current UTC offset, and defaults to yours.

Occurrences are computed in that zone, not converted from UTC after the fact. 0 9 * * 1 means nine in the morning locally, in January and in July.

Daylight saving

Because the calculation happens in the routine's zone, a 09:00 schedule stays at 09:00 across daylight-saving transitions. Two edge cases are worth knowing:

• Spring forward. A time inside the skipped hour does not exist on that date. Avoid scheduling between 02:00 and 03:00 in zones that shift there.
• Fall back. A time inside the repeated hour exists twice. The scheduler advances past an occurrence once it has been claimed, so a routine runs once, not twice — but the local clock reading can look surprising.

If a routine's timing is contractual — a financial close, a report due at a fixed UTC instant — set the timezone to UTC and do the arithmetic yourself.

Tick behaviour

The operations tick runs every minute. Each tick claims due routines, executes queued runs, and retries due webhook deliveries. Claims are atomic, so overlapping ticks never duplicate a run.

A routine is due when its computed next occurrence has passed and its status is active. Activation is what sets the first occurrence; a draft or paused routine has none.

Choosing a cadence

• Prefer the reader's schedule. A Monday-morning brief that arrives Monday at 06:00 is read; the same brief at 16:00 on Friday is not.
• Stagger routines. If six routines fire at 0 9 * * 1, they compete for the same gateway capacity and the same attention. Spread them across the hour.
• Match the window to the cadence. A weekly routine reporting a monthly window mostly repeats itself.
• Do not schedule faster than the work changes. A fifteen-minute routine over data that updates daily spends tokens to produce the same answer.

Timezone and schedule changes

Changing either the cron expression or the timezone is a material change: the routine returns to draft, its next occurrence is cleared, and it needs a new manual proof before it will run on the new schedule.