Format bulk queue: no queue webhook, no cancel-queue endpoint

A Sume Format bulk queue has no webhook and no cancel endpoint. Poll GET /v1/format-run-queues/{queue_id} for progress, register communication.webhook_url on each item for completion, and stop a batch by canceling its child runs one at a time. The Bulk runs docs are explicit on all three.

Knowing this before you queue 100 items saves you from looking for controls that do not exist.

Which controls exist on a queue?

The queue is a server-side list of ordinary Format runs with a concurrency window of 1 to 16, not a different engine.

How do I stop a batch?

Canceling a child marks that item canceled and frees its slot for the next queued item, which means canceling running children alone just lets the window start new ones. To stop the whole batch, you must also stop the queued items. The docs describe no call for that, so plan for it: keep batches small enough that you could let one finish, and give each item its own spend cap.

What you can do is cancel the children that already have a run_id. This lists them from the queue and cancels each:

QUEUE_ID="frq_..."
curl -sS "https://api.sume.com/v1/format-run-queues/$QUEUE_ID" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  | jq -r '.data.items[] | select(.status == "running") | .run_id' \
  | while read -r RUN; do
      curl -sS -X POST "https://api.sume.com/v1/format-runs/$RUN/cancel" \
        -H "Authorization: Bearer $SUME_API_KEY" | jq -r '.data.cancel_effect'
    done

What does completed mean?

Queue completed means every item is terminal, not that every item succeeded. Branch on counts.failed and counts.canceled. A failed item shows only a coarse error such as format_run_failed; the reason is on the child receipt. An item that never started a run keeps its index with run_id: null and the create-run failure in error, and the rest of the queue continues.

What about the idempotency key?

Mint a fresh Idempotency-Key per batch. A replay with the same { concurrency, items } returns 202 and the old queue, with no idempotency_hit field, and the same key with a different payload is 409 idempotency_conflict with details.queue_id naming the original. Keys are scoped to one Format.

Canceled children never send a webhook, so a webhook-only batch needs the queue poll to see them. For recovering failures, see retrying failed items.

How should I size a batch given these limits?

Since you cannot cancel a queue, the size of the batch is your only brake. The queue accepts 1 to 100 items and a concurrency window of 1 to 16, and each item is a normal run with its own spend cap and its own webhook. A bad item fails the whole create with 400 invalid_request and a details.index, before any queue exists, so nothing is dispatched or charged for a malformed list.

• Put a generation_spend_cap_usd on every item so the worst case is a known sum.
• Split a large sheet into several queues, each with its own Idempotency-Key, so you can stop between them.
• Store the frq_ id and each run_id as you read them: there is no list-queues call.
• Poll the queue with backoff; the read budget is separate from create, and a 429 or 503 does not mean the queue stopped.