A 340-product catalog: four Sume bulk queues of 100, 100, 100 and 40

A Sume bulk queue accepts 1 to 100 items, so a 340-product catalog needs four queues: three of 100 items and one of 40. Each item is the same body as a single Format run, and each queue is created with POST /v1/formats/{handle}/{slug}/bulk-runs. Split the list in order, give every queue its own idempotency key, and keep a mapping from queue and item index back to your product rows.

The arithmetic and the limits

concurrency is a required integer from 1 to 16 and sets how many child runs stay in flight inside one queue. The docs also say that child runs still go through ordinary Format-run admission, including workspace generation concurrency, so creating four queues does not mean four times as many runs are processed at the same moment.

Steps

Do the split in your own code so it is repeatable.

• Chunk the product list into slices of at most 100, keeping the original row number for each product.
• Send each slice as items, with a per-item generation_spend_cap_usd and, if you want per-item callbacks, a communication.webhook_url.
• Store each returned queue id (frq_) with the slice it came from.
• Poll each status_url with backoff until the queue status is completed, then read counts.failed and counts.canceled and look at the items that did not complete.

What Sume does not do

There is no queue-level webhook, no list-queues endpoint and no cancel-queue endpoint. To stop work you cancel a child run, and the next queued item then takes the free slot. A bad item rejects the whole create with 400 invalid_request and details.index, so a typo in product 87 of queue 2 blocks queue 2 and nothing else.

Replaying a spent key returns 202 with the old queue, so do not reuse catalog-nov-q1 for a corrected list; use a new key and a new queue. And completed only means every item is terminal, so a queue with failures is still completed.

Keeping rows and videos together

Every item keeps its zero-based index within its queue, and the items come back in the order you submitted them. So product 137 in your sheet is item 36 of queue 2. Write that mapping down when you create the queue and not when you read the results.

The queue item gives only a status, a run id and a short error. To learn why a child failed, read the run receipt at GET /v1/format-runs/{run_id}. For a catalog of this size it is worth writing a small loop that lists the failed indexes, reads each receipt, and puts the failed rows into a fifth, smaller queue with new keys once you have fixed the cause.