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

# Batch process media

> Run one model on many inputs in a single request, get one callback when the batch finishes.

## What you'll do

Process a folder of product shots through one model in a single call. One callback fires when every item is done.

## Prerequisites

* A Runflow API key. [Create one.](https://app.runflow.io/settings/api-keys)
* The model you want to run. Pick one from [`/models`](/models).
* A list of input URLs or asset IDs.

## Steps

<Steps>
  <Step title="Create the batch">
    `POST /v1/models/{model_id}/batches` with an array of items, where `{model_id}` is the slash-delimited provider/model path shown on the model page. Each item is a separate run.

    ```bash theme={"dark"}
    curl -X POST https://api.runflow.io/v1/models/runflow/background-replace/batches \
      -H "Authorization: Bearer $RUNFLOW_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "items": [
          { "input": { "image_url": "https://...01.jpg", "prompt": "white studio" } },
          { "input": { "image_url": "https://...02.jpg", "prompt": "white studio" } },
          { "input": { "image_url": "https://...03.jpg", "prompt": "white studio" } }
        ],
        "callback_url": "https://your-server.com/webhook"
      }'
    ```

    Response:

    ```json theme={"dark"}
    { "id": "01J0...", "status_code": "queued", "items_total": 3 }
    ```
  </Step>

  <Step title="Poll or wait">
    Either poll [`GET /v1/batches/{id}`](/api-reference/batches/get-batch-detail) or wait for the callback. Batch records expose `status_code`; terminal callback payloads expose the same value as `status`. Batches can also finish as `partial_succeeded`.
  </Step>

  <Step title="Read items">
    [`GET /v1/batches/{id}/items`](/api-reference/batches/list-batch-items-with-live-execution-state) returns one entry per input with the resolved `run_id`, `status_code`, and outputs.
  </Step>
</Steps>

## Verify it worked

```json theme={"dark"}
{
  "id": "batch_01J0...",
  "status_code": "succeeded",
  "items_total": 3,
  "items_succeeded": 3,
  "items_failed": 0
}
```

<Check>`items_failed: 0`? You're done.</Check>

## Troubleshooting

| Symptom                         | Likely cause               | Fix                                                      |
| ------------------------------- | -------------------------- | -------------------------------------------------------- |
| Some items fail, others succeed | Per-input validation error | Read each failed item's `failure_message`.               |
| Whole batch fails fast          | Auth or quota              | Check the [balance](/concepts/pricing).                  |
| Callback never arrives          | URL not reachable          | See [Callbacks: local development](/concepts/callbacks). |

## Related

<CardGroup cols={2}>
  <Card title="Runs" icon="play" href="/concepts/runs">Single-input lifecycle.</Card>
  <Card title="Callbacks" icon="webhook" href="/concepts/callbacks">Async result delivery.</Card>
</CardGroup>