Bulk queue concurrency 16 on Sume is a window, not a speed promise

The concurrency field on a Sume bulk Format queue, from 1 to 16, is the most children the queue keeps running at once. It is a ceiling on your own window, not a speed guarantee. A queue of 100 ad items at concurrency 16 works through the items in waves of at most 16, and the workspace's generation concurrency still applies to every child, so the real pace can be lower than the number you sent.

What the field does and does not do

The bulk-runs page defines the request: concurrency between 1 and 16, and items between 1 and 100, each with the same body as a single run. The response is a 202 with a queue receipt that has counts, items and a status_url. Nothing in the docs promises a completion time, so any time estimate you make is yours.

The wave arithmetic

With 100 items and concurrency 16, the number of waves is ceil(100 / 16) = 7, because 6 waves cover 96 items and a seventh covers the last 4. Wall time is then roughly the number of waves times the length of a typical child, if nothing else is limiting. A video child can take minutes, so budget on that order, and measure one run before you promise a deadline.

Dropping concurrency to 4 gives ceil(100 / 4) = 25 waves. That is slower, but it smooths spend, since fewer children are in flight and reserved at once.

Choosing a number

Pick a high value when speed matters and your balance is deep, and a low one when you want to watch the first results before the rest start. Remember that a spend ceiling is not part of the queue. Use generation_spend_cap_usd in each item body for per-run limits, and check your balance before you start.

curl -sS -X POST https://api.sume.com/v1/formats/sume/sume-video-hook/bulk-runs \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Idempotency-Key: ads-batch-01" \
  -H "Content-Type: application/json" \
  -d '{"concurrency": 4, "items": [
    {"instruction": "Hook A", "generation_spend_cap_usd": 5},
    {"instruction": "Hook B", "generation_spend_cap_usd": 5}
  ]}'

Reading the finish

A status of completed means every item is terminal, not that every item succeeded. Read the counts, including failed. A child that cannot start becomes a failed item with run_id null, and the queue carries on. There is no queue webhook, so use a per-item communication.webhook_url or poll status_url, and there is no cancel-queue endpoint, so cancel a single child at its run endpoint.

What we did not measure

We did not time a queue for this article. The numbers above are arithmetic from the documented limits, and your real pace depends on the Format and the model it uses.

A rule of thumb for ad tests

For a first pass over a hook grid, use a mid value such as 8. You get most of the parallelism, and if the first results show a broken prompt you have only half a window in flight to cancel. For a repeat of a known-good grid, go to 16. Neither number changes the price of a run; it only changes how many are in progress at once, and so how much balance is reserved at one moment.

Cancel at the child, not the queue. If a hook is wrong, cancel its run at /v1/format-runs/{run_id}/cancel and let the rest continue. Items that already finished keep their results.

If a queue is slower than the arithmetic above, check the workspace first: other jobs share the same generation concurrency, and your children wait their turn. A lower concurrency value will not fix that, and a higher one will not either, since the workspace limit sits above it. Read the counts on the status URL to see how many items are running and how many are queued.

Because every child reserves its own spend, the amount reserved at one moment is about the window size times the per-run reserve. At concurrency 16 with a $5 cap per item, that is up to $80 of exposure at once, and at 4 it is $20. Pick the window so that the exposure fits your balance.