POST /api/v1/batches
Run the same steps once per row. Write {{column}} in a step’s prompt or options wherever a row’s value goes. Each row is an ordinary run: checked before anything is charged, charged step by step, and refunded when a step fails.
dry_run to see the price, then again without it to run.
The rows
Send exactly one of these.
A batch runs up to 1,000 rows, and your plan’s batch size is the ceiling: Minotaur runs 50 rows with AI steps, Kraken 1,000. Headings are matched without case, spaces or punctuation. A
{{variable}} no column answers is refused with unknown_variable before anything runs.
The steps
steps or recipe, as POST /api/v1/runs reads them. A variable can go in a prompt or an option:
Files
A row’s own file wins over the shared one. Steps that make their own file (
generate, text-to-voice) need neither.
A picture option, end-frame or second-reference, can hold {{column}} too. Each row’s cell, a link or a Vault file id, is then that row’s own picture.
Keeping a set consistent
Budget and the check
A batch also pauses when the balance runs out, with the row it couldn’t start back in the queue. Top up, then resume.
Following it
POST answers 202 with the batch. Poll GET /api/v1/batches/{id}, or pass webhook_url and read batch.completed when every row has settled. Endpoints can subscribe to batch.completed too.
status is running, paused (paused_reason is budget or credits), complete or cancelled. Rows come 100 at a time: page with offset and limit.
Links that didn’t open
A row whose link can’t be fetched fails on its own, without a charge, and the rest of the batch runs. This covers the link infile_column and a row’s picture in a {{column}} option. failed_inputs lists every such row, on every page and in batch.completed:
row is the row’s index. rerun fetches those links again, which helps when a site was briefly down. For a wrong link, send those rows again in a new batch.
Results
GET /api/v1/batches/{id}/results is the sheet you sent, with status, review, result_name, result_url, credits, tries and error on the end. format=jsonl is one row per line instead. Links are signed for a day.
Changing a batch
POST /api/v1/batches/{id}/{action}:
Over MCP
run_batch takes the same fields, and get_batch polls it. See MCP.
