Schedules
Run an agent automatically on a cron schedule in any timezone.
Schedules
A schedule fires an agent on a recurring cron schedule, seeding each run with a kickoff message. Use it for recurring work — a daily report, a nightly sweep, a weekday digest.
Create a schedule
Open an agent's Schedules and add one: pick the cron expression, the timezone, and the kickoff message each run should start with. Schedules can be enabled and disabled without deleting them.
POST /v1/schedules. All four fields are required.
curl https://agents.clusterbase.dev/v1/schedules \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"agent": "agt_3f9c2a",
"cron": "0 9 * * 1-5",
"timezone": "America/New_York",
"kickoff": [{ "type": "text", "text": "Publish today'\''s engineering digest." }]
}'{
"id": "sched_a1b2c3",
"agent_id": "agt_3f9c2a",
"cron": "0 9 * * 1-5",
"tz": "America/New_York",
"kickoff": [{ "type": "text", "text": "Publish today's engineering digest." }],
"enabled": true,
"next_fire_at": "2026-06-17T13:00:00Z",
"last_fired_at": null
}| Field | Notes |
|---|---|
agent | The agent id to run. Must be one you own. |
cron | A standard 5-field cron expression, e.g. 0 9 * * 1-5 (09:00, Mon–Fri). |
timezone | An IANA timezone, e.g. America/New_York. Cron is evaluated in this zone. |
kickoff | Text content blocks seeded as the user.message for each fired run. |
The response reports next_fire_at (the next UTC instant the schedule will fire)
and last_fired_at.
How firing works
A background dispatcher polls for due schedules and fires each as a new session on the schedule's agent, appending the kickoff message to start the turn. Firing is at-most-once: the next fire time advances and commits before the run starts, so a crash mid-fire skips that occurrence rather than running it twice.
Manage a schedule
Enable or disable, or change the cron/timezone/kickoff, with PATCH:
curl -X PATCH https://agents.clusterbase.dev/v1/schedules/sched_a1b2c3 \
-H "Authorization: Bearer $CLUSTER_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "enabled": false }'Delete it with DELETE /v1/schedules/sched_a1b2c3.
To watch what a fired run did, open its session and read or stream its events.