12 days of deals: 12 videos in one Sume bulk queue

To make a 12-days-of-deals video series, send one POST /v1/formats/{handle}/{slug}/bulk-runs request with 12 items, one per deal day, and a concurrency of your choice from 1 to 16. Sume queues the 12 Format runs on its side and keeps up to concurrency of them in flight, so you do not run a loop on your laptop. The call answers 202 with a queue id that starts with frq_ and a status_url to poll.

The queue shape below comes from Bulk runs (read 2026-10-06). Each item is an ordinary Format run, so what a single deal video costs and how it looks is decided by the Format you call, not by the queue. Read Calling a Format first if you have not called a Format over the API.

How should I split the 12 days into items?

One item per day, in the order you want them to start. Each item takes the same body as a single run, and must name at least one of instruction, input, previous_run_id, or attachments. Put the deal itself in input and the day in the instruction, so the Format can keep one look across all 12 days.

• A queue holds 1 to 100 items, so 12 days is one queue, and a 31-day December calendar would also fit in one.
• A bad item fails the whole create with 400 invalid_request and a details.index that names the row. Sume dispatches nothing in that case, so fix the row and send again.
• Mint a fresh Idempotency-Key for each batch. If you replay a spent key with the same body, you get 202 and the old queue back, not a second one.

What does the queue do with concurrency 4?

The server keeps 4 child runs in flight. When one finishes, fails, or is canceled, the next queued item starts at once, until the list is drained. The docs give the example of concurrency: 3 with 8 items, where the 202 receipt shows three running and five queued. By the same rule, 12 items at concurrency: 4 start as 4 running and 8 queued.

curl -sS -X POST "https://api.sume.com/v1/formats/yourhandle/daily-deal/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: twelve-days-2026-batch-1" \
  -d '{
    "concurrency": 4,
    "items": [
      { "instruction": "Day 1 of 12", "input": { "deal": "Gift sets, 20% off" } },
      { "instruction": "Day 2 of 12", "input": { "deal": "Candles, 2 for 1" } },
      { "instruction": "Day 3 of 12", "input": { "deal": "Cozy socks, 15% off" } }
    ]
  }'

How do I know the series is done?

Poll status_url, which is GET /v1/format-run-queues/{queue_id}. The queue is completed when every item is terminal, and that is not the same as every deal video succeeding. Read counts.failed and counts.canceled before you call the series finished, and read each failed child at GET /v1/format-runs/{run_id} to learn why.

The queue has no webhook of its own. A webhook can be set per item through that item's communication.webhook_url, the same as on a single run.

• Key scope: the key needs formats:write to create and formats:read to poll.
• Service-account keys cannot create Format runs or bulk queues and get 403 insufficient_scope.
• There is no list-queues endpoint, so store the queue id when you create it.

What if one day needs a redo?

Do not rerun the queue. Cancel or leave the other items alone and redo that day as a single run, or revise it with previous_run_id. A canceled child frees its slot for the next queued item, so the window keeps moving.