Queue 20 ad runs overnight with Format bulk runs

Sume lets you queue up to 100 Format runs in one request with POST /v1/formats/{handle}/{slug}/bulk-runs, and run them with a concurrency window you set. Twenty ad runs is one request with concurrency: 3 and 20 items. Higgsfield's changelog says Ads Studio batches up to 20 ads per product; this is the equivalent shape for a Format-based workflow.

Everything below comes from Sume's Bulk runs page, read 2026-10-02, plus the Higgsfield changelog for the 20-ad figure.

What does the request look like?

A bulk request is a server-side queue of ordinary Format runs, so each item is the same unit of work as a single run: one sandbox, one agent turn, one run receipt. The envelope is two keys, concurrency and items. Send a fresh Idempotency-Key per batch; replaying a spent key returns 202 with the old queue.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-ad/bulk-runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ads-batch-2026-10-02-a" \
  -d '{
    "concurrency": 3,
    "items": [
      { "instruction": "Ad 1: headline Gift idea" },
      { "instruction": "Ad 2: headline New in" }
    ]
  }'

How do I know the batch finished?

Poll GET /v1/format-run-queues/{queue_id}. The queue itself has no webhook; communication.webhook_url is set per item. The docs also warn that completed means every item is terminal, not that all succeeded, so branch on counts.failed.

What scopes and keys do I need?

A key with formats:write creates the queue and formats:read polls it. Service-account keys cannot create Format runs or bulk queues and fail with 403 insufficient_scope. Keys made before the Format trigger shipped lack the scopes; create a new key.

What about spend?

Each item can bind its own generation_spend_cap_usd. Set it per item rather than trusting the batch total. See Budget a 20-ad batch before you run it for the pattern.

Keep a small ledger on your side: the queue id, the batch key you used, and the date. Because replaying a spent key returns the old queue rather than a new one, the ledger tells you whether you are looking at a fresh batch. When the queue reports terminal, list the failed children, fix the cause, and send only those items again as a new batch with a new key.