Schedules
Run your cron jobs as HTTP calls you can see.
A schedule calls your endpoint on a cron timetable. Every call is a run, signed, retried and recorded like a task, so "why didn't the 03:00 report run?" has an answer. Replace crontab, CronJob pods and Cloud Scheduler with the same server that runs your queues.
A cron expression, a timezone and a URL.
Create a schedule from code, the CLI or the dashboard, or declare it in workly.yaml and deploy it with your app. Setting a schedule is declarative: it ends up with exactly the settings you gave, and the response lists its next five runs, so you can check the expression before relying on it.
The handler is an ordinary route. It answers 2xx when the work is done; anything else is retried.
from workly import Workly
workly = Workly() # WORKLY_URL, WORKLY_API_KEY
workly.schedules.put(
"nightly-report",
cron="0 3 * * *",
timezone="Europe/Stockholm",
url="https://api.example.com/reports/nightly",
payload={"kind": "daily"},
)from workly import SignatureVerificationError, verify_signature
@app.post("/reports/nightly")
def nightly_report():
try:
verify_signature(request.get_data(), request.headers)
except SignatureVerificationError:
abort(401) # a 4xx isn't retried
# The slot this run is for, not the clock: a retried
# or late run still builds the right day's report.
day = request.headers["Workly-Scheduled-For"][:10]
build_report(day, run_id=request.headers["Workly-Run-Id"])
return "", 204What a schedule does that crontab doesn't.
Crontab runs a command and forgets it. A Workly schedule keeps every run, decides what happens when runs collide or the server was down, and retries a failed call before telling you.
In your timezone
Five-field cron read in an IANA timezone. Across daylight saving, a time in the skipped hour runs right after it, and one in the repeated hour runs once.
One run per slot
A run is created once per scheduled time, even when a replica fails over at that moment. Each run has its own ID, the same on every attempt.
When runs overlap
With overlap: skip, the default, a run due while the last one is still going is recorded as skipped, with the reason. With allow, they run side by side.
After downtime
After an outage, missed: skip records the most recent missed time as skipped; catch_up runs it once. A day down never replays a day of runs.
Retried like a task
Three attempts per run by default, with backoff, so a failing run gives up before a frequent schedule's next one. Every attempt is kept with its response.
Run now, retry, pause
Run a schedule now without moving its timetable, retry any finished or skipped run, or pause it during an incident. All from the dashboard, the CLI, the API or MCP.
Know which slot it is
Workly-Scheduled-For carries the time the run is for, so a late or retried run still does the right day's work. Workly-Run-Id deduplicates.
Hear how it went
Give a schedule an on_complete URL and each run calls back with its outcome. Or start a workflow instead of calling a URL.
Separate from queues
A schedule has its own settings and history and never uses a queue's limits, so a backlog of tasks can't delay the 03:00 job.
Every scheduled time has a run, including skipped ones.
The Schedules page shows each schedule's next run, its last run and a strip of recent ones. A skipped run says why it was skipped, and a failed run has every attempt with its status code, error and response body. A run keeps the request as it was sent, even after the schedule changes.
Failed runs alert you by email or Slack, and your coding agent can ask the same questions over MCP.
- Nov 13, 03:00succeeded200 · 1.2s
- Nov 12, 03:00succeeded200 after 2 attempts
- Nov 11, 03:00skippedoverlap: previous run still going
- Nov 10, 03:00failed503 Service Unavailable
- Nov 9, 03:00skippedmissed: no server was running
# workly.yaml, applied with `workly deploy`
version: 1
schedules:
nightly-report:
cron: "0 3 * * *"
timezone: Europe/Stockholm
url: https://api.example.com/reports/nightly
payload: {kind: daily}
overlap: skip # the default
missed: catch_up # run once after downtime
on_complete:
url: https://api.example.com/reports/nightly-doneWhat to know before you move a job.
A minute at the shortest
Cron has no seconds field here. For work every few seconds, enqueue delayed tasks instead.
One request per run
A run is one HTTP request, with a timeout of up to 30 minutes. For longer jobs, have the run enqueue tasks, or start a workflow.
History is kept for a while
Finished runs are kept for the retention period (7 days by default, 30 on Pro), but each schedule's latest run is always kept, so a monthly job still shows how it last went.
Questions
- How do I find out why a cron job didn't run?
- Open the schedule in the dashboard. Every slot has a run: a skipped run says whether it was an overlap with the previous run or a time missed while no server was running, and a failed run has every attempt with its status code, error and response body. Over MCP, an agent gets the same answer from get_schedule.
- Can Workly replace Kubernetes CronJobs or Cloud Scheduler?
- Yes, for jobs that can run as an HTTP request to your app. Instead of a pod per run or a GCP-only scheduler, the schedule calls an endpoint you already serve, with retries, a run history and a run-now button, from the same server as your queues.
- What happens if the server is down at the scheduled time?
- With missed: skip (the default), the most recent missed time is recorded as a skipped run, so you can see it, and the schedule carries on. With missed: catch_up, that time runs once. Either way, a long outage doesn't replay every missed run.
- Can a schedule run more than once for the same time?
- The run is created once per scheduled time, even across failovers. Delivery is at least once, as for tasks, so a handler can still see a retry: use the Workly-Run-Id header to deduplicate.
- Can a schedule start a multi-step job?
- Yes. Give it a workflow instead of a url, and each run starts a run of that workflow, with the schedule's payload as its input. With overlap: skip, a slow workflow run never has a second one started alongside it.
Try it in five minutes.
workly dev gives you a server and dashboard on your laptop with nothing else to start, and the Python and TypeScript SDKs let your app enqueue to it. Or sign in to hosted Workly and get a workspace and an API key in a minute, free on the Hobby plan.