Bulk runs
The real sheet-driven POST /v1/formats/mobidoo/live-commerce/bulk-runs Mobidoo fired — envelope, raw item body, and how to poll the queue.
Mobidoo uses two methods to run live-commerce. The
Live Commerce API page gives the
single-run method with typed clips: one POST …/runs, a receipt with
opening[] / middle[] / closing[], and thread-based clip retry.
This page gives the other method, a sheet-driven batch. One row of the
broadcast sheet becomes one item. The full sheet becomes one
POST …/bulk-runs. The schema keeps only full_video, the one field that the
batch uses. The 2026-08-28 HBS No.45–65 batch used this shape. This page gives
that batch in full, so that your backend can make the same body.
This method does not replace the clip schema. For typed clips and per-scene
retry, continue to use mobidoo/live-commerce/v1.
Workspace key
The rule is the same as for all Mobidoo Format calls. Use a
Mobidoo team workspace API key (a key created under the Mobidoo team, not a
personal key). If you use a personal key to call mobidoo/live-commerce, the
call fails with 403 workspace_key_required. Refer to
Team Formats need a team key.
The key must have formats:write to create the queue and formats:read to
poll the queue. You cannot add scopes to a key after you create it. Create a
new key.
If you are not in the Mobidoo workspace yet, ask 허채원 (Chase Huh) for an invite on Slack. You can also send an email to chase@sume.com. Refer to Workspace access.
The call
Keep the body in a file. When each row has its own VO, the body is much too long for a shell heredoc.
Create a new Idempotency-Key for each batch ($(uuidgen)). If you send a
used key again, the API returns 202 and the old queue. The API does not
start a new queue.
The envelope
bulk-runs-body.json has two keys. All other data is in each item.
The 2026-08-28 batch sent concurrency: 2 and 20 items: HBS No.45 to
No.65, but not No.50. That row had no completed draft. Remove such rows on
the client side. There is no “empty item” that you can send.
The item sequence is the sequence in which you send the items.
items[i].index on the receipt is that position. Thus, keep your own map of
each sheet row to its index.
The create call returns 202 with a frq_… queue. At that time, the first
concurrency items are in progress. These values identify the batch above:
queue frq_cfd22d14-68db-4aeb-9816-404a79f0badf, live-commerce v38, and
counts at create 20 total / 2 running / 18 queued. Only the key that created
that queue has access to it. You cannot GET the queue with your key.
The Bulk runs page gives the full envelope contract, the
limits (concurrency 1–16, items 1–100), the queue receipt shape, and all
error codes.
Item 0 — the raw body
Each item is the same as the body of one POST …/runs. The block below is
item 0 (sheet No.45) as the batch sent it, with two changes:
communication.webhook_url is a placeholder, and the spend cap uses the
current generation_spend_cap_credits field with an example value. The other
19 items have the same six keys, with the data of their own rows.
What each key is doing
| Key | Notes |
|---|---|
instruction | Prose and the raw sheet row. The tab-separated block is the sheet line, copied with no change. The quoted block is the full approved VO. No step parses the text before the Format reads it. |
input | The same row again, as structured JSON. Thus, your backend does not depend on the Format to parse the TSV again. script.segments has the VO as one long block, not as one object for each cut. |
output_schema | mobidoo/live-commerce/desk-iamdry/v1, strict: false, and only full_video as a required field (SumeMediaFile#). If a batch publishes only the assembled cut, it is better not to ask for clip arrays that the batch will not read. |
primary_output_key | "full_video". |
generation_spend_cap_credits | 8000 for each item. This value is the ceiling for that one child run, not for the queue. Twenty items can use twenty caps. |
communication | The terminal webhook for each item. This page shows it as https://example.com/hooks/format-run. Set it to your own endpoint. |
desk-iamdry/v1 is a schema name that applies only to its request. It is not
a new partner contract. When you bind this schema, the schema changes what that
run returns. The schema does not rebase mobidoo/live-commerce/v1.
instruction and input each give the row, because the two keys have
different functions. instruction is guidance. input is data. Refer to
what is carried.
Also obey the size limits in
Size: two limits.
The API rejects input if it has more than 2 MiB (2097152 UTF-8 bytes) or more
than 64 top-level properties. Below these limits, the API carries the full
value into the run. When the API carries instruction into the run, the API
cuts the text at approximately 4 000 characters. The API gives no error for
this cut.
After the 202
- The queue has no webhook. Each item has its own
communication.webhook_url. There is no callback at the queue level. Pollstatus_url(GET /v1/format-run-queues/{queue_id}) to get the progress. - The queue status
completeddoes not mean “all succeeded.” It means that all items are terminal. Examinecounts.failedandcounts.canceledto select the next step. - Read the failures on the child run. Use
items[i].run_idto callGET /v1/format-runs/{run_id}. The queue item has only the generalformat_run_failed. - Each child is a usual Format run. Thus, you can repair a weak row on its own thread with
previous_run_id. But you can do this only when the body binds the clip schema. With onlyfull_video, there are no scene ids that you can name.
Next
- Bulk runs — the platform queue contract, how to poll, and errors
- Live Commerce API — one run, the clip schema, and clip retry
- Best practices — create → receipt → clip-retry on one thread
- Structured output — the rules to bind a schema