Run 100 Formats overnight for an agency: Sume bulk queue explained

Post the whole list once to Sume bulk runs and let the server drain it. A bulk request is a server-side queue of ordinary Format runs: up to 100 items, a concurrency window of 1 to 16, one sandbox and one agent turn per item. Your laptop does not drive the fan-out, so closing it overnight does not stall the batch.

What the first response tells you

Create returns 202 with a format.run_queue and already fills the window. With concurrency 3 and 8 items the receipt shows three items running and five queued. When one finishes, the next starts immediately, so the window stays full until fewer than three remain.

Completed is not succeeded

The queue is completed when every item is terminal, and finished_at is then set. An item ends as completed, failed or canceled. Branch on counts.failed and counts.canceled before you tell a client the batch is done. To see why a child failed, read GET /v1/format-runs/{run_id}; the queue item only carries a generic format_run_failed code.

Pick a window for the job

• Video Formats run for minutes per child, so a window of 3 to 4 finishes 100 items in roughly 25 to 33 passes of the slowest child. That is arithmetic, not a measured time.
• Each item can carry its own instruction, input, attachments and generation_spend_cap_usd, so one bad row cannot spend without bound.
• There is no list-queues endpoint. Save the queue id you get back.

Poll loop

QUEUE=$(curl -sS -X POST "https://api.sume.com/v1/formats/your-handle/product-promo/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"concurrency":3,"items":[{"instruction":"clip 1"},{"instruction":"clip 2"}]}')
QUEUE_ID=$(echo "$QUEUE" | jq -r '.data.id')
STATUS=$(echo "$QUEUE" | jq -r '.data.status')
while [ "$STATUS" = "queued" ] || [ "$STATUS" = "running" ]; do
  sleep 60
  QUEUE=$(curl -sS "https://api.sume.com/v1/format-run-queues/$QUEUE_ID" \
    -H "Authorization: Bearer $SUME_API_KEY")
  STATUS=$(echo "$QUEUE" | jq -r '.data.status')
done
echo "$QUEUE" | jq '.data.counts'