Scheduled

A schedule is a saved Agents automation that runs on a cadence: instructions, a model, a cron expression, and a spend cap. When it fires, Sume runs it as an Agent in a fresh thread and returns a structured run receipt.

A cadence is the whole point. If you want to call Sume from your own backend when your user does something, you want the Format API instead — same run engine, same receipt, addressed per call and with your inputs. Reach for a schedule when nothing triggers the work except the clock.

Schedules are authored in the Agents dashboard, or by asking the Agent in chat to set one up for you. The Developer API can list them, read them, start runs, and monitor runs — it cannot create or edit them.

The rest of Scheduled lives on three pages linked from here: Create a schedule, Runs and results, and Advanced: run a schedule via API.

Scheduled and the Actions API. The product is called Scheduled. The HTTP API namespace is still /v1/actions, ids are aut_…, and objects come back as object: "action" — those names are stable and are not changing. Read "Action" in this page as the wire spelling of a schedule.

Schedule vs. generation job

A schedule run is not a job. It does not appear in /v1/jobs and it does not use the job lifecycle described in Jobs and results.

	Schedule run	Generation job
Started by	A cron schedule, or `POST /v1/actions/{action_id}/runs`	`POST /v1/{family}-1.0/...`
Unit of work	Saved instructions executed by an Agent in a new thread	One model invocation
Read back from	`/v1/action-runs/{run_id}`	`/v1/jobs/{id}`
Statuses	`queued`, `processing`, `completed`, `failed`, `canceled`, `skipped`	See Jobs and results
Result shape	`output` projected onto an output schema, plus `artifacts`	Job `result`
Overlap policy	`on_active_run` (`skip` or `reject`)	None

Use a generation job when you want one model invocation. Use a schedule when you want saved instructions that an Agent carries out on a cadence, possibly across several generations.

If the task itself changes on every call and there is nothing worth saving, you want Agent Completions instead — same agent, no saved object, instruction supplied per request.

Anatomy of a schedule

GET /v1/actions and GET /v1/actions/{action_id} return this shape.

Field	Notes
`status`	`active` or `inactive`. An `inactive` schedule rejects API runs.
`trigger_type`	`cron` or `api`. Fixed at create time.
`api_trigger_enabled`	When `true`, `POST /v1/actions/{action_id}/runs` is allowed. A `cron` schedule can also enable it.
`cron`	`{ "expr", "timezone", "next_run_at" }`, or `null` for the API-only case.
`output_schema`	Default structured output binding (`{ "name", "strict" }`), or `null` for the built-in default. Bind one in the dashboard; see Structured output.
`generation_spend_cap_usd_micros`	Per-run generation cap in USD micros. `null` means the $1.00 default applies.
`invoke_url`	The schedule's own invoke endpoint.

The instructions text is deliberately omitted from the public shape. Read and edit instructions in the dashboard.

Triggers

The trigger type is chosen at create time and is immutable afterwards:

Scheduled (cron) — the default. Runs on a 5-field cron expression in an IANA timezone.
API call (api) — an advanced option: no cadence, runs only when your service calls POST /v1/actions/{action_id}/runs. See Advanced: run a schedule via API.

A cron schedule can additionally set api_trigger_enabled to accept API runs on top of its cadence. An API-only one never has a cadence.

Where schedules live

Author and monitor them at https://www.sume.com/agents/scheduled. See Create a schedule for the dashboard flow.

Limits

Limit	Value
`input` properties	64
`input` size	2097152 UTF-8 bytes (2 MiB)
Default generation spend cap	$1.00 (`1000000` USD micros) when unset
Per-run spend cap override	Clamped to `min(request, schedule cap)` — it can lower the cap, never raise it
`Idempotency-Key` length	1–255 characters
`limit` on list endpoints	1–100, default 50

What schedules do not support yet

Be aware of these gaps before you design around them:

Signing secrets are not self-serve yet. communication.webhook_url is accepted, validated, stored, and delivered on api.dev.sume.com and api.sume.com. The contract is documented at Run webhooks.
No events endpoint. events_url on a run receipt is always null — run lifecycle events are not exposed over the API. Use status_url and result_url.
No pagination. List responses always return has_more: false and next_cursor: null.
No MCP tool and no CLI command. Schedules are not exposed over MCP or the CLI.
No write endpoints. The Developer API cannot create, edit, or delete a schedule.