Format run stuck in queued: read queue.state and retry_after_seconds

A Format run that stays queued is not necessarily stuck. Read queue.state on the status payload: waiting means pickup is still inside the normal window, and runtime_unavailable means the run has waited past it with nothing claiming it. In that second case retry_after_seconds says how long to back off, and a state that lasts more than a few minutes is worth a support ticket with the request_id.

These fields are in the Runs and results docs. This post collects what the docs say you can and cannot do.

What is in the queue block?

The small status_url payload carries queue next to status, next_action, cancelable and expires_at. Two details matter for a dashboard.

What should my code do about it?

Keep polling with backoff, and treat runtime_unavailable as a signal for your own alerting rather than as a failure. The run object is still a valid run: the receipt exists, next_action is poll_status, and nothing about it has failed. Remember that creating the run already passed the wallet check, so a queued run has not spent generation yet, but you should not assume a particular cost outcome. Read usage on the receipt instead of guessing.

Two other limits apply. The run is force-finalized as failed at its expires_at, which is 90 minutes from creation, or sooner when the run is older than 25 minutes and has been silent for 10. And a run you no longer want can be canceled with POST /v1/format-runs/{run_id}/cancel; the response says whether the call stopped a run (canceled) or found it already finished (no_op).

curl -sS "https://api.sume.com/v1/format-runs/$RUN_ID/status" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq '.data | {status, next_action, expires_at, queue}'

Is it my concurrency limit?

Possibly, and it is a different thing. Workspace generation concurrency still applies to Format runs, and request rate limits do not raise it. A bulk queue shows the same distinction: with concurrency: 3 and eight items, three are running and five queued on the first receipt by design, and a child that cannot start is marked that item's failed instead of stalling the window. A single run that sits in queued with queue.state: waiting is just inside the window.

The queue state of a bulk item is a separate field, covered in bulk runs. Do not confuse the bulk queue's queued item status with the single-run queue block described here.

When do I open a ticket?

Quote the request_id from the receipt, the run id, and what queue said. The docs ask for exactly those, and say not to send API keys, signing secrets or raw media URLs. Every response also carries the x-sume-request-id header. A single runtime_unavailable reading is not a case; one that persists for more than a few minutes is.

What does the SDK do for me?

In TypeScript, waitForRun with family: "format" defaults to a 10 minute timeout and a 2 second poll interval, and exceeding the timeout throws SumeRunTimeoutError. A Format run can legitimately outlive that default, since long-form host video typically takes 15 to 30 minutes, so pass a longer timeout and use expires_at as the real ceiling. A status read that fails transiently does not end the wait.