Schedules
A schedule calls an HTTP endpoint on a cron timetable: a nightly report, a sync every 15 minutes, a weekly cleanup. Each call is a run, delivered, signed and retried like a task, with every attempt recorded. It’s cron for HTTP endpoints, with a history and a “run now” button.
Schedules are separate from queues: a schedule has its own settings (retries, timeout, what to do when runs overlap) and history, and no queue’s limits apply to it. Its only tasks are callbacks, if you ask for them.
Queue → Task → AttemptSchedule → Run → AttemptCreate a schedule
Section titled “Create a schedule”curl -X PUT localhost:7337/v1/schedules/nightly-report -d '{ "cron": "0 3 * * *", "timezone": "Europe/Stockholm", "url": "https://api.example.com/reports/nightly", "payload": {"kind": "daily"}}'PUT is declarative, like queues: the schedule ends up with exactly the settings given, and omitted ones go back to their defaults. The response includes next_runs, the next five times it will run, so you can check the expression.
From code:
client.schedules.put( "nightly-report", cron="0 3 * * *", timezone="Europe/Stockholm", url="https://api.example.com/reports/nightly", payload={"kind": "daily"},)await workly.schedules.put('nightly-report', { cron: '0 3 * * *', timezone: 'Europe/Stockholm', url: 'https://api.example.com/reports/nightly', payload: { kind: 'daily' },});Or from the CLI:
workly schedules put nightly-report https://api.example.com/reports/nightly \ --cron '0 3 * * *' --timezone Europe/Stockholm -d '{"kind": "daily"}'Or keep it in a workly.yaml and deploy it with workly deploy (configuration as code):
version: 1schedules: nightly-report: cron: "0 3 * * *" timezone: Europe/Stockholm url: https://api.example.com/reports/nightly payload: {kind: daily}Cron expressions
Section titled “Cron expressions”Five fields: minute, hour, day of month, month and day of week.
| Expression | Runs |
|---|---|
*/15 * * * * |
every 15 minutes |
0 * * * * |
every hour, on the hour |
0 3 * * * |
every day at 03:00 |
0 9 * * mon-fri |
weekdays at 09:00 |
30 4 * * sun |
Sundays at 04:30 |
0 0 1 * * |
the first of every month at midnight |
Fields take *, numbers, lists (1,15), ranges (1-5), steps (*/10, 0-30/5) and three-letter names for months and days (jan, mon). Day of week runs from 0 (Sunday) to 6, and 7 is Sunday too. The macros @hourly, @daily, @weekly, @monthly and @yearly work as usual. When both day fields are restricted, as in 0 0 13 * fri, a day matches if either does (the 13th, or any Friday), as in classic cron. Seconds aren’t supported; the shortest interval is a minute.
The expression is read in the schedule’s timezone, an IANA name such as Europe/Stockholm (default UTC). Across daylight saving changes, a time in the skipped hour runs right after it (02:30 runs at 03:00), and a time in the repeated hour runs once.
Settings
Section titled “Settings”| Setting | Default | |
|---|---|---|
cron |
required | When to run. |
timezone |
UTC |
|
url |
required | The endpoint to call. |
workflow |
none | Instead of url: start a run of this workflow, with payload as its input. |
method, headers, payload or body, content_type |
POST |
The request, as for tasks. |
timeout_seconds |
30 |
How long to wait for a response. |
max_attempts |
3 |
Attempts per run before it fails. |
min_backoff_seconds, max_backoff_seconds, backoff_multiplier |
5, 300, 2 |
Backoff between retries, as for queues. |
retry_on_4xx |
false |
Retry 4xx responses other than 408 and 429. |
overlap |
skip |
What to do when a run is due while the previous one is still going. |
missed |
skip |
What to do about times missed while the server was down. |
on_complete |
none | A callback, {url, headers}, called with a summary each time a run finishes. |
With workflow, a schedule sends no request of its own. Each run starts a workflow run, with the schedule run’s ID as its idempotency key, and succeeds once it has started; a workflow that doesn’t exist yet is retried like a failed request. The schedule run links to the workflow run (workflow_run_id), and workflow_run_status says whether it’s still going or how it ended. For overlap, the schedule counts as running until the workflow run finishes, so with skip a slow workflow never has two scheduled runs at once. method, headers, body and content_type don’t apply.
Retries are fewer and shorter than a queue’s by default, so a failing run gives up before a frequent schedule’s next one.
Overlap. With skip, a run that comes up while the previous run is still pending or running (or, for a schedule with workflow, while the workflow run it started is still going) is recorded as skipped, with skip_reason: overlap, and not delivered. With allow, it runs alongside. Runs you start by hand always run.
Missed runs. A run is missed if no server could start it within a minute of its time. skip records the most recent missed time as a skipped run with skip_reason: missed and carries on; catch_up runs it once. Either way, a server that was down for a day doesn’t make up every run it missed.
Each run has a state: pending, running, succeeded, failed, cancelled or skipped. A run is created once per scheduled time, even if the server fails over at that moment; like tasks, its delivery is at least once.
workly runs ls --schedule nightly-report # newest firstworkly runs ls --state failed # failed runs of every scheduleworkly runs get <run id> # the run and its attemptsIn the API, GET /v1/runs takes the same filters: ?schedule=nightly-report, ?state=failed. A run’s started_at is when its first attempt started, and last_duration_ms how long its latest attempt took.
A run keeps the request as it was when the run was created, so it shows what was sent even after the schedule changes. Retries use the schedule’s current retry settings.
- Run now:
POST /v1/schedules/{name}/trigger(orworkly schedules trigger, or the dashboard’s Run now) creates a run withtrigger: manualand delivers it at once, even while the schedule is paused. It doesn’t change when the schedule next runs. - Retry a run:
POST /v1/runs/{id}/retrydelivers a failed, cancelled, succeeded or skipped run again, with a fresh set of attempts. Retrying a skipped run delivers the time it skipped. - Pause:
POST /v1/schedules/{name}/pausestops new runs; runs already pending finish. A paused schedule haspaused_at, nonext_run_atand emptynext_runs;next_runs_if_resumedare the times it would run if resumed now. Times that pass while it’s paused aren’t run. - Delete: deleting a schedule deletes its runs.
Finished runs are kept for WORKLY_RUN_RETENTION (by default WORKLY_RETENTION, 7 days), except each schedule’s latest run, which is always kept, so a monthly job still shows how it last went.
Handling a run
Section titled “Handling a run”Your endpoint gets the request with these headers:
| Header | |
|---|---|
Workly-Run-Id |
The run, the same on every attempt. Use it to deduplicate. |
Workly-Schedule |
The schedule’s name. |
Workly-Scheduled-For |
The scheduled time (RFC 3339). Use it, not the clock, to decide which day or hour a late or retried run is for. |
Workly-Attempt |
The attempt number. |
Workly-Signature, Workly-Timestamp |
The signature, as for tasks: verify it with the SDKs’ verify_signature / verifySignature. |
Runs don’t carry Workly-Task-Id or Workly-Queue, so one handler can tell a scheduled call from a task if it receives both.
Monitoring
Section titled “Monitoring”The dashboard’s Schedules page shows each schedule’s next run, last run and recent runs; a schedule’s page has its upcoming times and every run with its attempts. Over MCP, get_schedule answers “why didn’t the 03:00 report run?” from the skipped and failed runs.
For alerts, workly_schedule_last_success_timestamp_seconds tells you when each schedule last succeeded; alert when it’s older than the schedule’s period. See metrics.