Scheduled AI video agent runs: cron, API triggers, and receipts

A Sume 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. You author schedules in the Agents dashboard; the Developer API can list and read them, start runs, and monitor runs, but cannot create or edit them.

Every detail below comes from the Scheduled docs and its pages on creating a schedule, runs and results, and the API trigger.

How do I create a scheduled agent run?

Open Scheduled and use the Create control, or ask the Agent in chat to set one up. The product is called Scheduled, but the API namespace is /v1/actions, ids are aut_…, and objects come back as object: "action". The dashboard flow:

• Write instructions and pick a model. Empty instructions cannot run.
• Set the cadence: a 5-field cron expression in an IANA timezone. Hourly, daily, and weekly presets write the expression for you.
• Set the generation spend cap. When unset, the effective default is $1.00 per run. A caller can lower it for one run with generation_spend_cap_usd, never raise it.
• Optionally bind an output schema. By default output is projected onto sume/action-run-output/v1: { text, images[], videos[], audio[], files[] }.
• Set the schedule to Active. While it is Inactive, API runs are rejected with 409 action_inactive.

Should my schedule use cron or an API trigger?

The trigger type is fixed at create time. cron is the default and runs on the cadence. api is an advanced option with no cadence: the schedule runs only when your service calls POST /v1/actions/{action_id}/runs. A cron schedule can also set api_trigger_enabled to accept API runs on top of its cadence; an API-only schedule never gains a cadence.

If your backend should call Sume when your own user does something, the docs point to the Format API instead: same run engine, same receipt, addressed per call with your inputs. See What is a Sume Format?

How is a schedule run different from a generation job?

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

How do I start a run from my own service?

The schedule must be active with api_trigger_enabled: true, and your key needs actions:read and actions:write. Keys created before the API-call trigger shipped lack these scopes and fail with 403 insufficient_scope, so create a new key at API keys. Service-account keys cannot create Action runs.

An accepted run returns 202 with a receipt whose object is action.run. input reaches the Agent as data, not instructions: at most 64 properties and 2 MiB. Send an Idempotency-Key of 1–255 characters; replaying it with the same payload returns the original receipt with 200 and idempotency_hit: true, and a different payload returns 409 idempotency_conflict. A {handle}/{slug} vanity path also works, but store the opaque aut_… id, which never changes.

curl -sS -X POST "https://api.sume.com/v1/actions/$ACTION_ID/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"input":{"product_name":"Aurora Headphones"}}'

What happens if a run is already active?

Only one run of a schedule is active at a time; on_active_run decides what happens to a second request. A 200 does not mean the work finished, so branch on the receipt's status.

• skip (the default) returns 200 with status: "skipped" and skip_reason: "previous_run_active". A run row is recorded.
• reject returns 409 action_run_in_progress, and no run is recorded.

How do I get the result?

Poll GET /v1/action-runs/{run_id}/status and branch on next_action: poll_status while the run is queued or processing, retry_later after a skip, and none once it is terminal. GET /v1/action-runs/{run_id}/result returns the full receipt only when the run is terminal, and 409 run_not_completed before that. A completed run populates output and artifacts, and primary_output_url is the resolved URL for primary_output_key.

usage.billable_amount_usd_micros counts generation spend only. It excludes the agent's own LLM turn, which bills the separate Agent wallet, and GET /v1/usage remains the authoritative billing record. POST /v1/action-runs/{run_id}/cancel needs actions:write and is idempotent. To skip polling, set communication.webhook_url and receive one signed POST with the terminal receipt; see signed webhooks for video runs.

What does Scheduled not support yet?

The docs list these gaps:

• Signing secrets are not self-serve yet.
• There is no events endpoint. events_url on a run receipt is always null.
• There is no MCP tool and no CLI command for schedules.
• There are no write endpoints. The Developer API cannot create, edit, or delete a schedule.
• Schedules owned by a team workspace are not reachable over the public API yet.