Can a partner bulk-run your shared Format? Queue and spend are theirs
A grantee can POST .../bulk-runs at your handle and slug with its own team key. The queue, child runs and spend are theirs, and you cannot poll their queue.
Yes: a workspace with an accepted grant can call POST /v1/formats/{owner-handle}/{slug}/bulk-runs with its own team key and a formats:write scope. The API resolves the grant on that route the same way it does for a single run, so the queue, its child runs and the spend belong to the grantee, and you as the owner do not see them.
The bulk docs describe the queue contract but do not spell out the grant case; the behavior here comes from how the API routes the vanity bulk path, so treat it as current behavior and re-check the live API reference before building a product on it.
What stays the same
Everything in the bulk contract is unchanged: concurrency is an integer from 1 to 16, items has 1 to 100 entries, each entry is the same body as a single run, and an Idempotency-Key makes a retry safe. A bad item fails the whole create with a 400 and details.index, and nothing is dispatched.
A grantee needs a key created in its own team workspace. A personal key gets 403 workspace_key_required, and a pending or revoked grant answers 404 format_not_found.
curl -sS -X POST "https://api.sume.com/v1/formats/acme/product-promo/bulk-runs" \
-H "Authorization: Bearer $PARTNER_TEAM_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: drop-oct-batch-1" \
-d '{"concurrency":4,"items":[
{"instruction":"Drop 1: spring tote","generation_spend_cap_usd":8},
{"instruction":"Drop 2: linen shirt","generation_spend_cap_usd":8}]}'Who sees what
| Question | Answer |
|---|---|
| Whose spend are the child runs? | The calling workspace's, as with any shared run. |
| Can the owner poll the grantee's queue? | No: a queue that a different owner has answers 404 format_run_queue_not_found. |
| Which limits apply? | The grantee's concurrency and queue capacity. |
| Does the owner's Status or API trigger apply? | Yes: format_inactive and format_api_trigger_disabled hit every caller. |
| What if the owner revokes mid-queue? | New calls fail closed; the docs do not describe a queue already created, so check before you rely on it. |
Sizing
A queue's concurrency is a window of child runs, and the workspace's own generation concurrency still applies, so a window of 16 on a workspace that processes four at a time will queue the rest. Look at the grantee's generation_limits before choosing the window, and send a cap on each item: the worst-case spend of a queue is items times the per-item cap, and there is no queue-level limit.
Reading the result as the grantee
The 202 returns a queue receipt with status_url. Poll it with formats:read and a key from the same workspace. The queue's status becomes completed when every item is terminal, which says nothing about success, so read counts.failed and the per-item error objects.
Each item has an index that matches the position in your items array and a run_id once its child run starts. A child that could not start has a null run_id and an error code, and the rest of the queue carries on.
Limits
If you are the owner and need a partner's batch results, ask for the queue's counts and the child run receipts from them. The owner has no read path to a grantee's queue or runs.
Sources
Related posts
More in Formats
- Price-drop sale videos for 200 SKUs: two bulk queues, one key each
A bulk queue holds at most 100 items. For 200 marked-down SKUs, send two queues, give each its own Idempotency-Key, and track both queue ids yourself.
- Release a 50-SKU holiday batch in two bulk queues: 5 first, 45 after
Submit 5 SKUs as a pilot queue, review the clips, then queue the other 45. Sume bulk queues take 1-100 items at concurrency 1-16. Runnable payload builder.
- Format run, schedule or Agent Completion for repeatable holiday ads
Use a Format when only inputs change, Scheduled when the clock starts the work, Agent Completions when the task changes. Set a spend cap on each.
- Retry only the missing ad variants with previous_run_id on a Format
When a variants run returns some clips as null, continue it with previous_run_id and name the missing slots, so you do not pay for the finished variants again.
Written by Sume