Scheduled triggers

A schedule is a small record bound to one workflow: a cron expression, a stored input object, an enabled flag, and two timestamps the engine maintains for you — last_run_at and next_run_at. An in-process loop wakes roughly every 20 seconds, finds every enabled schedule whose next fire time has arrived, and starts a run through the full engine. Everything below is the exact behaviour of that loop and the API that manages it.

The cron expression

Five space-separated fields in the standard order. All evaluation is in UTC — there is no per-schedule timezone, so convert local wall-clock times to UTC before you write the expression.

Field syntax

Every field accepts the same four token shapes. Within a single field you may combine them with commas — the field matches the union of all entries.

Example expressions

Day-of-month and day-of-week together

When both the day-of-month and day-of-week fields are restricted — that is, neither is * — the schedule fires when either matches. This is standard cron, and it is a common source of surprise. When at least one of the two is *, only the other constrains the day.

Validation

Expressions are validated on create and on any cron edit. The check both parses the fields and confirms the expression fires at least once within the next year, so impossible dates like 30 February are rejected too. Failures return 400 naming the exact field and problem:

{ "detail": "Invalid cron expression: cron needs exactly 5 fields: minute hour day-of-month month day-of-week" }
{ "detail": "Invalid cron expression: minute: 75 outside 0-59" }
{ "detail": "Invalid cron expression: day-of-week: range '5-2' outside 0-7" }
{ "detail": "Invalid cron expression: hour: step must be >= 1" }
{ "detail": "Invalid cron expression: cron expression never fires within a year" }

How the scheduler runs

Scheduling is in-process. A background task in the backend's lifespan runs one tick every 20 seconds (TICK_SECONDS) on a worker thread — no Celery, no APScheduler, no external cron. Each tick loads every enabled schedule whose next_run_at is at or before the current time in a single query, then processes them in order.

• Because ticks are ~20s apart and next_run_at always lands on a minute boundary, a schedule fires within about 20 seconds after its boundary and never before it. Minute precision is guaranteed; sub-minute precision is not
• next_run_at is always the first fire time strictly in the future, found by scanning forward minute by minute up to roughly 366 days
• last_run_at is set to the tick time on every attempt, including skipped ones — it records the last time the scheduler evaluated the schedule, not the last successful run
• After each attempt, next_run_at is recomputed from the cron relative to that tick. A missed or skipped slot is not retried — the schedule advances to its next matching minute, so schedules never try to catch up on a backlog
• A scheduled run is created with status pending and handed to the engine exactly like a manual trigger: graph validation, checkpoints, human gates, retries, cost attribution, evals, and the WebSocket event stream all apply
• Each successful trigger is audit-logged as schedule_run on the workflow, with details carrying the run_id, schedule_id, and the cron string

Order of checks per due schedule

For every due schedule, the tick runs these checks in sequence and stops at the first that fails. Whatever the outcome, last_run_at and next_run_at are updated afterward.

Self-disabling

A schedule turns itself off only in two situations, and both are permanent until you re-enable it with PUT /api/schedules/{id}:

• The workflow it points at has been deleted — the scheduler cannot resolve a graph to run
• Recomputing next_run_at finds no fire time within a year (a defensive guard; the expression was validated at create time, so this is rare)

Managing schedules

Full CRUD lives under /api. Creating, editing, and deleting schedules require the create_edit_workflows capability (editor or admin); listing requires only view. Every schedule mutation is audit-logged.

{ "cron": "0 9 * * 1-5", "input": { "source": "daily-digest" } }
// →
{
  "id": "b8d1f2a90c34",
  "workflow_id": "9bc62f209c52",
  "workflow_name": "Support Triage Crew",
  "cron": "0 9 * * 1-5",
  "input": { "source": "daily-digest" },
  "enabled": true,
  "last_run_at": null,
  "next_run_at": "2026-07-08T09:00:00Z",
  "created_at": "2026-07-07T14:21:08Z"
}

{ "enabled": false }

Full lifecycle by curl

# create: every weekday at 09:00 UTC, with a stored input payload
$ curl -s -X POST http://localhost:8000/api/workflows/9bc62f209c52/schedules \
    -H "content-type: application/json" \
    -d '{"cron": "0 9 * * 1-5", "input": {"ticket": "daily digest sweep"}}'
# → 201 { "id": "b8d1f2a90c34", "enabled": true, "next_run_at": "2026-07-08T09:00:00Z", ... }

# list the whole workspace fleet
$ curl -s http://localhost:8000/api/schedules

# list schedules for just this workflow
$ curl -s http://localhost:8000/api/workflows/9bc62f209c52/schedules

# retune the cadence — recomputes next_run_at
$ curl -s -X PUT http://localhost:8000/api/schedules/b8d1f2a90c34 \
    -H "content-type: application/json" \
    -d '{"cron": "*/15 * * * *"}'

# pause without losing the schedule
$ curl -s -X PUT http://localhost:8000/api/schedules/b8d1f2a90c34 \
    -H "content-type: application/json" \
    -d '{"enabled": false}'

# remove it entirely
$ curl -s -X DELETE http://localhost:8000/api/schedules/b8d1f2a90c34   # → 204