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
- 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.
- 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.
- 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.
Written by Sume