Schedules
Run an Agent task daily, on an interval, or on a cron expression, with a durable history of every occurrence.
What a schedule is
A saved run request and a timing rule. Every occurrence starts a new session from the saved request; the Workspace must already exist so recurring work cannot create spaces without bound. Schedules are created and managed by owners and admins from the console or with an account session; API keys with read can inspect them and, with execute, trigger an occurrence.
{ "name": "Daily website check", "timing": { "kind": "daily", "time": "09:00", "timezone": "Asia/Shanghai" }, "missed_policy": "skip", "run": { "task": "Open the website, inspect changes and save a report. Do not submit forms.", "model_id": "platform", "workspace_id": "ws_…", "network": { "mode": "direct" }, "max_turns": 20, "timeout_ms": 300000 }}run takes the run fields — profile_id, reasoning_effort, record_video, network, integration_ids, … — except session_id and browser_id.
Timing
| Kind | Shape |
|---|---|
daily | { "kind": "daily", "time": "09:00", "timezone": "Asia/Shanghai" } |
interval | { "kind": "interval", "minutes": 60, "timezone": "UTC" } — 1 to 43,200 minutes |
cron | { "kind": "cron", "cron": "0 9 * * 1-5", "timezone": "Asia/Shanghai" } — five numeric fields with *, ,, - and /; one of day-of-month or day-of-week must be * |
POST /v1/schedules/preview with a timing object returns the next five occurrences (UTC and local) from the same parser execution uses.
missed_policy decides what happens to ticks the platform was not running for: lateness under a minute executes; older ticks skip (default) or run_once (one overdue execution for all of them).
Routes
| Method and path | Result |
|---|---|
GET /v1/schedules, GET /v1/schedules/{id} | The project's plans; one plan |
GET /v1/schedules/{id}/history | The latest 200 occurrences |
POST /v1/schedules | Create |
PATCH /v1/schedules/{id} | revision plus changed fields; { "revision", "enabled": false } pauses; resume recalculates from now |
DELETE /v1/schedules/{id} | { "revision" } |
POST /v1/schedules/{id}/run | {} with Idempotency-Key → 202; works while paused; { "retry_of": "occ_…" } retries a failed, cancelled or skipped occurrence |
Stale revisions answer conflict. Editing cancels occurrences that have not started; pause and delete do not cancel a run already admitted. A Profile or Workspace a schedule references cannot be deleted until the schedule changes.
Occurrences
States: pending, running, cleanup, succeeded, failed, cancelled, skipped. History keeps the request snapshot, scheduled time, trigger, run id, attempt count, public error and skip reason. When browser capacity is full, admission retries every 30 seconds, at most three times within five minutes, only before a run exists. An occurrence is never replayed automatically after a failure or restart — a retry is an explicit request that may repeat external effects.
for occurrence in client.schedules.history(schedule_id): print(occurrence["status"], occurrence.get("run_id"))client.schedules.run_now(schedule_id)for (const occurrence of await client.schedules.history(scheduleId)) console.log(occurrence.status, occurrence.run_id);await client.schedules.runNow(scheduleId);