Scheduled or Format API: does the clock or your user start the run?
A Sume Scheduled run fires on a cron; a Format run fires when your backend calls it. Same agent, same receipt, new trigger. How to choose without dupes.
Use Scheduled when only the clock starts the work, and use the Format API when something your user or your system did starts it. Both run the same agent and return the same kind of receipt. The difference is who owns the trigger and where the instructions live.
The decision in a table
The Sume docs frame it the same way: a schedule stores what to do, a Format stores how to do it.
| Question | Scheduled | Format API |
|---|---|---|
| Who starts it | A cron, or an API call to the saved schedule | Your backend, on each event |
| What is saved | Instructions, model, cron and spend cap | A recipe: style, output contract, playbook |
| What you send per run | Nothing, usually | An instruction and an input object |
| Where runs are read | /v1/action-runs/{run_id} | /v1/format-runs/{run_id} |
| Created through the API | No. Dashboard or chat only | Authoring has its own Contents API |
Pick Scheduled when
- The output is the same kind every week: a Monday teaser, a daily report, a monthly recap.
- No end user is waiting; the clock is the only input.
- You are happy to create and edit it in the Agents dashboard.
Pick the Format API when
- A customer action should produce a video: a new product, a finished order, a submitted brief.
- Inputs differ every time and you want them to land in a typed schema.
- You need a webhook to your own system, per-run spend caps, or a bulk queue of up to 100 runs.
A trap to avoid
Scheduled runs are not generation jobs. They do not appear in /v1/jobs and they do not use the job lifecycle. Their statuses include skipped, which a plain job does not have. If you build a dashboard on /v1/jobs, a schedule run will not show up there, so read /v1/action-runs/{run_id} for those.
The product is called Scheduled, but the HTTP namespace is still /v1/actions, with ids that start aut_. Those names are stable.
When neither fits
If the task changes on every call and there is nothing worth saving, use Agent Completions instead. You send the instruction each time and get a run receipt back. All three share the same engine, so you can start with the one that needs the least setup and move later.
Sources
Related posts
More in Agents
- Three ways to run the Sume video agent from code
Format runs, Scheduled runs and Agent Completions all start the same Sume agent. Pick by how often your task changes, then read the receipt the same way.
- A video agent run takes 15 to 30 minutes: design the waiting
Long-form video from an agent is minutes of work, not seconds. Email-me-when-ready, saved drafts and honest limits for a Sume Format run in your product.
- Run the Sume video agent from your backend with Agent Completions
POST /v1/agent/completions runs the same agent as the Sume Agents chat, with tools and media generation, and returns an async run receipt you poll or webhook.
- Safe automation for AI agents that call paid APIs
Keep agents read-only by default, keep secrets out of logs, and on hosted MCP send an idempotency_key, preview with dry_run, and cap with max_spend_usd.
Written by Sume