Scheduled

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

A cadence is the whole point. Do you want to call Sume from your own backend when your user does something? If so, use the Format API instead. The Format API has the same run engine and the same receipt. You address it on each call, and you give your inputs. Use a schedule when only the clock starts the work.

You create schedules in the Agents dashboard. You can also ask the Agent in chat to make one 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 is on three pages that this page links to: Create a schedule, Runs and results, and Advanced: run a schedule via API.

Scheduled and the Actions API. The name of the product is Scheduled. The HTTP API namespace is still /v1/actions, ids are aut_…, and the API returns objects as object: "action". Those names are stable and will not change. On this page, "Action" is the wire spelling of a schedule.

Schedule vs. generation job

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

	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 that an Agent executes 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 an Agent to do saved instructions on a cadence. This work can use several generations.

If the task changes on each call and you have nothing to save, use Agent Completions instead. It uses the same agent, with no saved object. You supply the instruction on each 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 permitted. 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. Refer to Structured output.
`generation_spend_cap_usd_micros`	The generation cap for each run, in USD micros. `null` means that the $1.00 default applies.
`invoke_url`	The invoke endpoint of the schedule.

The public shape does not include the instructions text. This is intentional. Use the dashboard to read and edit instructions.

Triggers

You select the trigger type at create time. After that, you cannot change it:

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

A cron schedule can also set api_trigger_enabled to accept API runs in addition to its cadence. An API-only schedule never has a cadence.

Where schedules live

Create and monitor schedules at https://www.sume.com/agents/scheduled. For the dashboard flow, refer to Create a schedule.

Limits

Limit	Value
`input` properties	64
`input` size	2097152 UTF-8 bytes (2 MiB)
Default generation spend cap	$1.00 (`1000000` USD micros) if not set
Per-run spend cap override	The API clamps a number > 0 to `min(request, schedule cap)`. It can lower the cap, but it can never raise it. `null` runs without the automation ceiling. The API rejects `0`
`Idempotency-Key` length	1–255 characters
`limit` on list endpoints	1–100, default 50

What schedules do not support yet

Before you make a design that uses schedules, know these gaps:

Signing secrets are not self-serve yet. The API accepts, validates, stores, and delivers communication.webhook_url on api.dev.sume.com and api.sume.com. Run webhooks documents the contract.
No events endpoint. events_url on a run receipt is always null. The API does not expose run lifecycle events. Use status_url and result_url.
No MCP tool and no CLI command. MCP and the CLI do not expose schedules.
No write endpoints. The Developer API cannot create, edit, or delete a schedule.