Polling a Sume agent run: next_action values and backoff

Poll a Sume agent run on status_url and branch on next_action, not on the status string. poll_status means keep waiting with backoff, retry_later means the run was skipped because another was active, and none means the run is terminal and there is nothing more to fetch. These three values are the full set on schedule runs, and Agent Completions use the same rule: poll until next_action is not poll_status.

The values

Use the URLs the receipt gives you

Each receipt carries status_url, result_url and cancel_url, and the docs ask you not to build URLs yourself. status_url returns a trimmed payload meant for loops: id, status, started_at, finished_at, next_action and cancelable.

result_url returns the full receipt only after the run is terminal. While the run is queued or processing it answers 409 run_not_completed with the current status in details.status, so do not treat that 409 as a failure.

Backoff, not a fixed sleep

Video runs take minutes, and long host videos usually take 15 to 30 minutes, so polling every second buys nothing and spends your read budget. The docs recommend exponential backoff in production. A 429 or 503 during a poll loop is temporary: the run and its spend continue, so wait for retry-after and carry on instead of cancelling.

A short poll loop is enough. Call status_url, stop when next_action is not poll_status, sleep with exponential backoff and jitter between calls, and cap the total wait with your own deadline. When the deadline passes, cancel through cancel_url only if the run is still cancelable, and then poll status_url until the status reads canceled.

What the receipt tells you at the end

Do not parse the status_url body for the result. It is trimmed on purpose. Fetch result_url once, after the run is terminal, and log the request_id with your own job id so a support question can be answered from one line.

• status: completed, failed, canceled or (for schedules) skipped.
• output and output_error: check output_error before you read output. A projection failure on an API run is a run failure.
• usage: generation spend against the cap. It is null when Sume could not read the spend, which is different from 0.
• request_id: log it.

Prefer a webhook, keep the poll as a backup

A run webhook removes the loop. It fires once when the run completes or fails, and a canceled or skipped run sends nothing, which is exactly when a poll still helps. After you cancel, poll status_url until payload.status is canceled, and do not wait for a POST that will not arrive.