Build a run status chip from the Format events phase timeline
Sume has no SSE stream for Format runs. Poll status_url and events_url to show queued, preparing, running and finalizing in your UI without faking progress.
Show a status chip, not a percentage. Sume does not stream Format run progress: there is no SSE or WebSocket channel, and events_url is a polled phase timeline with preparing, running and finalizing. A chip built on those phases is honest. A progress bar built on guesses is not.
What you can read
Every run receipt carries its own URLs, so you never build a path by hand.
| Receipt field | Returns | Use it for |
|---|---|---|
| status_url | Small payload: status, next_action, cancelable, expires_at, queue | The chip and the poll loop |
| events_url | Phase timeline: preparing, running, finalizing | A second line of text under the chip |
| result_url | Full receipt once terminal; 409 run_not_completed before | Reading the output |
| cancel_url | Stops the run | A Cancel button |
Map states to chip text
Keep the words close to the real states.
queued: Waiting to start. Ifqueue.stateisruntime_unavailable, say it is taking longer than usual.processingwith phasepreparing: Getting set up.processingwith phaserunning: Making your video. This can last 15 to 30 minutes for long-form host video.processingwith phasefinalizing: Saving the files.completed,failed,canceled: show the result or the error.
Poll without hurting yourself
Start at about five seconds and double the gap up to one minute. A one-second loop adds nothing and spends read budget. A 429 or 503 inside the loop is temporary: the run keeps going while you back off. Use expires_at on a non-terminal receipt as your ceiling, since Sume force-finalizes a run that exceeds it as failed.
Prefer the webhook for the final state
Use the poll only for the chip. For the result, take the signed format.run.terminal webhook and keep the poll as a backup for the day your endpoint is down. In TypeScript, the SDK's subscribeFormatRun wraps create-and-wait, and its onStatus callback reports statuses from a poll, not from a log feed (Embed a Format in your product).
What not to show
Do not show the agent's reasoning or logs. The events timeline does not contain them, and the API does not offer them. If a run did something you did not expect, open its thread in Agents and read the first message, which holds the exact text the agent received.
Sources
Related posts
More in Agents
- Stop an AI video agent overspending: the four Sume spend gates
An unattended Sume agent can only spend what four gates allow: the wallet, a per-run cap, a schedule ceiling, and a Format cap. Values and failure codes inside.
- Let a video agent read before it spends: MCP OAuth read, then write
Hosted MCP OAuth gives mcp:read by default and mcp:write by a consent toggle. Let an agent plan with reads, then enable write for paid calls.
- MCP wants a human in the loop: Sume gates for unattended agents
MCP says a human SHOULD be able to deny tool calls. For unattended agents, Sume adds scopes, idempotency keys and a required Agent Completions cap.
- Auditing agent tool calls: MCP log advice, Sume script_run journal
The MCP spec tells clients to log tool usage for audit. For Sume's script_run, the response includes a calls[] journal and child jobs[] to use with jobs_wait.
Written by Sume