Lost the bulk-run queue id? There is no list endpoint; replay the key
Sume has no list-queues or cancel-queue endpoint. If you lost the frq_ id, replay the create with the same key and body to get the queue back.
If your process crashed after POST .../bulk-runs returned but before you stored the frq_... queue id, you can still get it back: repeat the same create with the same Idempotency-Key and the identical { concurrency, items } body. Sume answers 202 with the queue that already exists. There is no list-queues endpoint and no cancel-queue endpoint in the public API, so the key is your only handle on a queue you did not write down.
What the API gives you and what it does not
The bulk-run surface is deliberately small: POST /v1/formats/{format_id}/bulk-runs, the vanity twin POST /v1/formats/{handle}/{slug}/bulk-runs, and GET /v1/format-run-queues/{queue_id}. Each child is an ordinary Format run, so you can cancel one with POST /v1/format-runs/{run_id}/cancel, but nothing cancels the whole queue in one call.
| Need | Available? | How |
|---|---|---|
| Create a queue | Yes | POST /v1/formats/{handle}/{slug}/bulk-runs, 1-100 items, concurrency 1-16 |
| Read a queue | Yes, with the id | GET /v1/format-run-queues/{queue_id} |
| List queues | No | Replay the key, or store ids yourself |
| Cancel a queue | No | Cancel each child run |
| Queue-level webhook | No | Per-item communication.webhook_url, plus polling |
Write the id down in the right order
The safe sequence has three steps. First, generate the batch key and write it to your database as pending before the network call. Second, call create and write the data.id next to the key. Third, poll the queue and update status. If the process dies between the first and second steps, a restart finds a pending key with no queue id and replays the create with the identical body. That is why you must store the body (or a way to rebuild it exactly) alongside the key: a different payload under the same key is a 409, not a recovery.
- Persist the key and the exact item list before the call.
- On restart, replay only batches that have a key but no queue id.
- Compare the returned
data.idwith any id you already hold. - Never mint a new key for a batch that might already exist: that submits the work a second time.
Why this matters more with cheaper clips
As per-second prices fall, batch sizes grow, and a lost 100-item queue is exactly the failure that burns money while you cannot see it. The children still run and bill, and each child is still readable at GET /v1/format-runs/{run_id} once you know its id. Stripe's idempotency guidance is built for this scenario, a connection error where you cannot tell whether the first request landed. Sume's bulk create follows the same contract, and the status-code quirk is covered in a separate post.
Sources
Related posts
More in Formats
- MAI-Voice-2.1 and Format runs: get the voiceover as its own file
A Format run cannot be told to use MAI-Voice-2.1, since its tools pick the audio model. Bind an audio field to get the voiceover track as a file.
- One Format run with five variants or a five-item bulk queue?
One run gives you five variants under one cap and one receipt. A bulk queue gives five receipts, a concurrency window up to 16 and per-item retry.
- Can a partner bulk-run your shared Format? Queue and spend are theirs
A grantee can POST .../bulk-runs at your handle and slug with its own team key. The queue, child runs and spend are theirs, and you cannot poll their queue.
- Price-drop sale videos for 200 SKUs: two bulk queues, one key each
A bulk queue holds at most 100 items. For 200 marked-down SKUs, send two queues, give each its own Idempotency-Key, and track both queue ids yourself.
Written by Sume