> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mediamonster.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a batch

> The same steps once per row of a sheet, or every combination of a few lists. A budget, a quality check and a results sheet.

`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](https://docs.mediamonster.app/api/runs.md): checked before anything is charged, charged step by step, and refunded when a step fails.

```bash theme={"theme":{"light":"github-dark","dark":"github-dark"}}
curl -X POST https://mediamonster.app/api/v1/batches \
  -H "Authorization: Bearer mm_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [{"tool": "generate", "prompt": "Studio photo of {{product}}, {{scene}}"}],
    "matrix": {
      "product": ["a red trainer", "a canvas tote"],
      "scene": ["on a beach at dawn", "on a wet city street"]
    },
    "naming": "{{product}}-{{scene}}",
    "budget": 100,
    "dry_run": true
  }'
```

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.

| Field | What it is |
| - | - |
| `rows` | A list of objects. Each key is a variable: `{"Product Name": "tote"}` is `{{product_name}}` |
| `csv` | A sheet's text, header row first. Commas or semicolons |
| `matrix` | Up to 4 lists. Every value is run with every value of every other list |

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`](https://docs.mediamonster.app/api/runs) reads them. A variable can go in a prompt or an option:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{"tool": "resize", "options": {"aspect": "{{ratio}}"}}
```

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

| Field | What it does |
| - | - |
| `url`, `upload_id`, `job_id`, `asset_id` | One file every row starts from: a product shot, a reference picture, a master video |
| `file_column` | The column holding each row's own file: a public link or a Vault file id. A link can be a direct file, a video page (YouTube, Vimeo and others), a Google Drive or Dropbox share, or a podcast episode. A link two rows share is fetched once. |

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

| Field | What it does |
| - | - |
| `locks.style` | Words added to the end of every prompt: a look, a palette, a lens |
| `locks.brand` | A brand id from [`GET /api/v1/brands`](https://docs.mediamonster.app/api/brands). Every step that takes a brand uses it |
| `naming` | What each result is called, from its row: `{{sku}}-{{colour}}`. `{{row}}` is the row's number |

## Budget and the check

| Field | What it does |
| - | - |
| `budget` | The most credits the batch spends. A row is started only while what's spent, plus what's running, plus that row's price stays inside it. Otherwise the batch pauses |
| `check` | `{"retries": 1}` checks each picture with [`image-qa`](https://docs.mediamonster.app/skills/reference/image-qa) and makes the ones that fail again, up to `retries` times (3 at most). `strict: true` remakes borderline pictures too. Each try is charged |

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.

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
{
  "id": "4b1e…",
  "object": "batch",
  "status": "running",
  "rows": {"total": 4, "waiting": 0, "running": 4, "complete": 0, "failed": 0, "skipped": 0},
  "credits_charged": 0,
  "budget": 100,
  "items": [{"index": 0, "row": {"product": "a red trainer", "scene": "on a beach at dawn"}, "status": "running", "tries": 1}],
  "poll_url": "/api/v1/batches/4b1e…",
  "results_url": "/api/v1/batches/4b1e…/results"
}
```

`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 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`:

```json theme={"theme":{"light":"github-dark","dark":"github-dark"}}
"failed_inputs": [
  { "row": 3, "url": "https://example.com/missing.jpg", "reason": "That link didn't open. Check it's public and points at a file" }
]
```

`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}`:

| Action | Body | What it does |
| - | - | - |
| `rerun` | `{"status": "failed"}` or `{"rows": [0, 4]}` | Runs those rows again, each as a new, charged try. `status` also takes `rejected`, `skipped` and `complete` |
| `resume` | `{"budget": 500}` | Carries on a paused batch. `{"budget": null}` takes the budget off |
| `cancel` | — | Starts no more rows. Rows already running finish |
| `review` | `{"rows": [0, 1], "review": "approved"}` | Marks rows `approved`, `rejected`, or clears the mark with `null` |
| `save` | `{"folder": "Campaigns/Spring"}` | Files the approved rows' results in the Vault, under their batch names. `{"all": true}` saves every finished row |

## Over MCP

`run_batch` takes the same fields, and `get_batch` polls it. See [MCP](https://docs.mediamonster.app/mcp.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.