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

# Batch

> Submit, list, poll, and delete asynchronous batches of inference requests. See https://openrouter.ai/docs/batch-quickstart.

## Overview

Submit, list, poll, and delete asynchronous batches of inference requests. See [https://openrouter.ai/docs/batch-quickstart](https://openrouter.ai/docs/batch-quickstart.md).

### Available Operations

* [list](#list) - List batches
* [create\_batches](#create_batches) - Create a batch
* [delete](#delete) - Delete a batch
* [get\_batches](#get_batches) - Get a batch

## list

Lists batches in the workspace of the authenticating API key, newest first. To fetch the next page, pass the previous page's `last_id` as `after`. List items omit `results`. Use `GET /batches/{id}` to get them. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart.md).

### Example Usage

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.list()

    while res is not None:
        # Handle items

        res = res.next()

```

### Parameters

| Parameter | Type | Required | Description | Example |
| - | - | - | - | - |
| `http_referer` | *Optional\[str]* | ➖ | The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application.  | |
| `x_open_router_title` | *Optional\[str]* | ➖ | The app display name allows you to customize how your app appears in OpenRouter's dashboard.  | |
| `x_open_router_categories` | *Optional\[str]* | ➖ | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.  | |
| `limit` | *Optional\[int]* | ➖ | Maximum number of batches to return, from 1 through 100. | 20 |
| `after` | *Optional\[str]* | ➖ | Batch id from the previous page's `last_id`. | batch\_7a4b02 |
| `status` | List\[[components.BatchListStatus](../../components/batchliststatus.mdx)] | ➖ | Repeat this parameter to include more than one status. | \[ "completed", "failed" ] |
| `created_after` | *Optional\[Any]* | ➖ | Only include batches created strictly after this timestamp. | |
| `created_before` | *Optional\[Any]* | ➖ | Only include batches created strictly before this timestamp. | |
| `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | ➖ | Configuration to override the default retry behavior of the client. | |

### Response

**[operations.ListBatchesResponse](../../operations/listbatchesresponse.mdx)**

### Errors

| Error Type | Status Code | Content Type |
| - | - | - |
| errors.BatchErrorResponse | 400, 401, 429 | application/json |
| errors.BatchErrorResponse | 500, 502 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |

## create\_batches

Creates a batch of requests that run asynchronously against a single endpoint (`/v1/chat/completions`, `/v1/responses`, `/v1/messages`, `/v1/embeddings`, `/v1/audio/speech`). Returns `202` with `status: "validating"`. Poll `GET /batches/{id}` for progress and results. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart.md).

### Example Usage: chatCompletions

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.create_batches(endpoint="/v1/chat/completions", model="openai/gpt-4o", completion_window="24h")

    # Handle response
    print(res)

```

### Example Usage: messages

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.create_batches(endpoint="/v1/messages", model="openai/gpt-5-nano", completion_window="24h")

    # Handle response
    print(res)

```

### Example Usage: providerPinned

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.create_batches(endpoint="/v1/chat/completions", model="google/gemini-3.6-flash", completion_window="24h")

    # Handle response
    print(res)

```

### Example Usage: responses

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.create_batches(endpoint="/v1/responses", model="openai/gpt-4o", completion_window="24h")

    # Handle response
    print(res)

```

### Parameters

| Parameter | Type | Required | Description | Example |
| - | - | - | - | - |
| `endpoint` | [components.Endpoint](../../components/endpoint.mdx) | ✔️ | N/A | |
| `model` | *str* | ✔️ | N/A | |
| `http_referer` | *Optional\[str]* | ➖ | The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application.  | |
| `x_open_router_title` | *Optional\[str]* | ➖ | The app display name allows you to customize how your app appears in OpenRouter's dashboard.  | |
| `x_open_router_categories` | *Optional\[str]* | ➖ | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.  | |
| `callback_url` | *Optional\[str]* | ➖ | HTTPS URL that receives a `batch.completed`, `batch.failed`, `batch.cancelled` or `batch.expired` webhook event when the batch reaches a terminal status. Must appear before `requests` in the request body. | |
| `completion_window` | [Optional\[components.BatchSubmitBodyCompletionWindow\]](../../components/batchsubmitbodycompletionwindow.mdx) | ➖ | N/A | |
| `input` | [Optional\[components.BatchInputReference\]](../../components/batchinputreference.mdx) | ➖ | A batch input file or table in your own storage, named in place of `requests`. Available to allowlisted callers on Google Vertex BYOK endpoints only. | |
| `provider` | [OptionalNullable\[components.BatchProviderPreferences\]](../../components/batchproviderpreferences.mdx) | ➖ | Batch provider routing preferences. Only `provider.only` and `provider.allow_fallbacks` are supported. | \{ "only": \[ "google-vertex" ] } |
| `requests` | List\[[components.Request](../../components/request.mdx)] | ➖ | The batch requests. Send exactly one of `requests` or `input`; `requests` must be the last field in the request body. | |
| `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | ➖ | Configuration to override the default retry behavior of the client. | |

### Response

**[components.BatchObject](../../components/batchobject.mdx)**

### Errors

| Error Type | Status Code | Content Type |
| - | - | - |
| errors.BatchErrorResponse | 400, 401, 402, 403, 404, 413, 422, 429 | application/json |
| errors.BatchErrorResponse | 500, 502 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |

## delete

Deletes a batch in a terminal status (`completed`, `failed`, `expired`, or `cancelled`) and its stored requests and results. Batches still in progress return `409`. Billing and usage records are kept. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart.md).

### Example Usage

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.delete(id="batch_abc123")

    # Handle response
    print(res)

```

### Parameters

| Parameter | Type | Required | Description | Example |
| - | - | - | - | - |
| `id` | *str* | ✔️ | The batch job id returned from submit. | batch\_abc123 |
| `http_referer` | *Optional\[str]* | ➖ | The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application.  | |
| `x_open_router_title` | *Optional\[str]* | ➖ | The app display name allows you to customize how your app appears in OpenRouter's dashboard.  | |
| `x_open_router_categories` | *Optional\[str]* | ➖ | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.  | |
| `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | ➖ | Configuration to override the default retry behavior of the client. | |

### Response

**[components.BatchDeletedObject](../../components/batchdeletedobject.mdx)**

### Errors

| Error Type | Status Code | Content Type |
| - | - | - |
| errors.BatchErrorResponse | 401, 404, 409, 429 | application/json |
| errors.BatchErrorResponse | 500, 502 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |

## get\_batches

Returns a batch with its status and request counts. Batches in a terminal status include `results`. Failed batches report the reason in `error.message`. See the [Batch API Quickstart](https://openrouter.ai/docs/batch-quickstart.md).

### Example Usage

```python theme={null}
from openrouter import OpenRouter
import os


with OpenRouter(
    http_referer="<value>",
    x_open_router_title="<value>",
    x_open_router_categories="<value>",
    api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:

    res = open_router.batch.get_batches(id="batch_abc123")

    # Handle response
    print(res)

```

### Parameters

| Parameter | Type | Required | Description | Example |
| - | - | - | - | - |
| `id` | *str* | ✔️ | The batch job id returned from submit. | batch\_abc123 |
| `http_referer` | *Optional\[str]* | ➖ | The app identifier should be your app's URL and is used as the primary identifier for rankings. This is used to track API usage per application.  | |
| `x_open_router_title` | *Optional\[str]* | ➖ | The app display name allows you to customize how your app appears in OpenRouter's dashboard.  | |
| `x_open_router_categories` | *Optional\[str]* | ➖ | Comma-separated list of app categories (e.g. "cli-agent,cloud-agent"). Used for marketplace rankings.  | |
| `retries` | [Optional\[utils.RetryConfig\]](../../models/utils/retryconfig.mdx) | ➖ | Configuration to override the default retry behavior of the client. | |

### Response

**[components.BatchObject](../../components/batchobject.mdx)**

### Errors

| Error Type | Status Code | Content Type |
| - | - | - |
| errors.BatchPaymentRequiredResponseError | 402 | application/json |
| errors.BatchErrorResponse | 401, 404, 410, 429 | application/json |
| errors.BatchErrorResponse | 500, 502 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* |