Cron triggers

A Worker with a scheduled handler can run on a schedule: a nightly export, a cache refresh, a reminder sweep. Set its schedules on the Worker’s Triggers tab under Cron triggers, or with PUT /api/v1/sites/{site}/triggers. triggers.crons in wrangler.jsonc isn’t read.

src/index.ts

interface Env {
  DB: D1Database;
}

export default {
  async scheduled(controller: ScheduledController, env: Env): Promise<void> {
    if (controller.cron === "0 3 * * *") {
      await env.DB.prepare("DELETE FROM sessions WHERE expires_at < ?")
        .bind(Date.now())
        .run();
    }
  },
};

controller.cron is the expression that fired and controller.scheduledTime the minute it fired for. The run’s fetch calls go through Outbound like a request’s.

Expressions

Five fields, separated by spaces, always in UTC:

Field	Values
Minute	0–59
Hour	0–23
Day of the month	1–31
Month	1–12, or jan–dec
Day of the week	0–7 (both 0 and 7 are Sunday), or sun–sat

Each field takes a number or name, *, a list (1,15), a range (mon-fri) or a step (*/15, 0-30/10). When both the day of the month and the day of the week are restricted, the schedule fires on either, as in standard cron.

Expression	Runs
*/15 * * * *	Every 15 minutes
0 3 * * *	03:00 UTC every day
30 8 * * mon-fri	08:30 UTC on weekdays
0 0 1 * *	Midnight UTC on the first of each month

A Worker can have up to 5 cron triggers, and the most often a schedule can run is once a minute.

Setting them from the API

crons replaces the Worker’s whole list; leave it out to keep the list and change only routes:

curl -X PUT https://digize.com/api/v1/sites/shop/triggers \
  -H "x-api-key: $DIGIZE_API_KEY" \
  -H "content-type: application/json" \
  -d '{"crons":["0 3 * * *","*/15 * * * *"]}'

An expression that isn’t five fields of these characters is refused with 400 invalid.

How they run

Workers for Platforms scripts have no schedules of their own, so Digize’s Dispatch Worker runs every minute, finds the schedules due that minute across every site, and calls each site’s scheduled handler. Sites run independently: one that fails or throws doesn’t hold up the rest. A run that fails isn’t retried; the next one comes at its next scheduled time.