Schedules
Run an agent automatically on a cron schedule in any timezone.
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. cron and timezone are always required. Then either
name an agent and a kickoff, or name a deployment that carries both.
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. Omit when deployment is set. |
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. Omit when deployment is set. |
deployment | Optional. A deployment id to run instead of a bare agent — see below. |
The response reports next_fire_at (the next UTC instant the schedule will fire)
and last_fired_at.
Run through a deployment
Set deployment instead of agent + kickoff and the schedule becomes just a
clock: the deployment supplies the agent, the kickoff, the VM environment, and
the credential vaults for every fired run. This is how a recurring run gets a VM
and vault credentials. Supplying agent or kickoff alongside deployment is
ambiguous and returns 400. A deployment on a saved (existing) environment is
refused at fire time — there's no caller around to provision against, so
scheduled runs use fresh, ephemeral VMs.
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.
If a schedule's agent has been archived, the dispatcher disables the schedule
(enabled flips to false) instead of firing it — archiving an agent stops it
from starting new sessions, so a bound schedule can no longer run.
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.