Skip to main content
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.
That’s 4 rows: every product with every scene. Send it once with 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:
Each different set of options the rows make is checked on its own, so a row asking for an aspect that doesn’t exist is refused up front, with its row number.

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. 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 in file_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.