Sume bulk queue says completed but some runs failed: read the counts

A Sume bulk queue reaches completed when every item is terminal. That is not the same as every item succeeding. Read counts.failed and the error on each row of items[] before you publish the batch, and fetch each child at GET /v1/format-runs/{run_id} for its own receipt and media.

What the queue is

POST /v1/formats/{handle}/{slug}/bulk-runs creates a server-side queue of ordinary Format runs. Each item is the same unit of work as one POST .../runs: one sandbox, one agent turn, one receipt. The body takes concurrency (1 to 16) and items (1 to 100). The accepted create returns 202 with a format.run_queue object, and the first concurrency items are already in flight.

Reading the receipt

counts.total equals items.length. counts.running includes an item that the API still treats as in flight.

A check that does not lie

Poll GET /v1/format-run-queues/{queue_id} and wait for status: completed. Then decide on the counts. This shell fragment fails the job if any child failed.

QUEUE="frq_example"
Q=$(curl -sS "https://api.sume.com/v1/format-run-queues/$QUEUE" \
  -H "Authorization: Bearer $SUME_API_KEY")
echo "$Q" | jq '.data.counts'
test "$(echo "$Q" | jq '.data.counts.failed')" = "0"

Things that surprise people

• The queue has no webhook. communication.webhook_url is per item, and the queue is polled through status_url.
• Every item runs with on_active_run: "allow". Sending skip or reject on an item does not stall the window.
• A bad item fails the whole create with 400 invalid_request and details.index, before any queue exists.
• There is no public list-queues or cancel-queue endpoint. Cancel a child with POST /v1/format-runs/{run_id}/cancel.

A realistic batch

The docs describe a production batch of this shape: a spreadsheet of broadcast rows, concurrency: 2, 20 items, one item per row. The client skips rows that have no finished draft, and each item binds its own output_schema and its own generation_spend_cap_usd.

That per-item cap is the useful part. A queue has no cap of its own, so the sum of your item caps is the most that the batch can spend. Add them up before you send, and keep the batch within what your wallet holds.

Fresh key for each batch

Mint a new Idempotency-Key for every batch. If you replay a spent key, the API returns 202 with the old queue, which looks like a new batch that finished instantly. Derive the key from the batch you intend, such as the sheet name and the week.