Event recap videos: one bulk queue, one run per session

For an event recap with one short video per session, send a bulk queue: POST /v1/formats/{handle}/{slug}/bulk-runs with one item for each session. The server keeps a window of 1 to 16 runs in flight and starts the next as one finishes, so you do not need a loop on your laptop. A queue takes 1 to 100 items, and each item is the same body as a single run.

The queue request

The request below uses a Format called acme/event-recap, which is a placeholder for a Format you own. Each item has its own instruction, input and spend cap. The Idempotency-Key is for the whole batch: replaying a spent key returns 202 with the old queue, so mint a new key for each batch.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/event-recap/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: summit-2026-recaps-batch1" \
  -d '{
    "concurrency": 2,
    "items": [
      { "instruction": "45 second recap, opening keynote", "input": { "session": "keynote" },
        "generation_spend_cap_usd": 30 },
      { "instruction": "45 second recap, workshop A", "input": { "session": "workshop-a" },
        "generation_spend_cap_usd": 30 },
      { "instruction": "45 second recap, closing panel", "input": { "session": "panel" },
        "generation_spend_cap_usd": 30 }
    ]
  }'

Reading the queue

The 202 receipt is a format.run_queue with an id like frq_…, counts, one row for each item and a status_url. Poll GET /v1/format-run-queues/{id} for progress. With concurrency: 2 and three items, the first receipt shows two items running and one queued.

The queue has no webhook. If you want a callback, put communication.webhook_url on each item; every child then sends its own terminal POST.

Failure handling for a recap batch

A queue that reports completed can still hold failed sessions. Read counts.failed and counts.canceled, then for each failed row open GET /v1/format-runs/{run_id}: the queue item only says format_run_failed, while the receipt's error gives the cause. A row that never started has run_id: null and the create error.

To redo one session, create a single run for it with the same Format and a new idempotency key, or continue the failed child with previous_run_id if it left artifacts. There is no public cancel-queue endpoint; cancel a child with POST /v1/format-runs/{run_id}/cancel.

Sizing the window and the caps

Pick concurrency from the capacity of your plan and from what you can review. The queue starts the next item as soon as a slot frees, but each child still goes through ordinary admission: the wallet, the workspace generation concurrency and the spend cap. If the plan allows fewer simultaneous generations than your window, children wait their turn, so a very large window does not make a batch faster.

Use per-item caps, as in the request above. A queue of 30 sessions with a $30 cap each can hold at most 30 x 30 = 900 dollars of cap in total, and the platform cap of $500 applies to each run and not to the queue. Read the sum of usage.billable_amount_usd_micros over the child receipts after the batch, and compare it to what you expected.