Batch - OpenRouter | Documentation

Overview

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

Available Operations

list - List batches
create_batches - Create a batch
delete - Delete a batch
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.

Example Usage

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]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`limit`	Optional[int]	:heavy_minus_sign:	Maximum number of batches to return, from 1 through 100.	20
`after`	Optional[str]	:heavy_minus_sign:	Batch id from the previous page’s `last_id`.	batch_7a4b02
`status`	List[components.BatchListStatus]	:heavy_minus_sign:	Repeat this parameter to include more than one status.	[ “completed”, “failed” ]
`created_after`	Optional[components.BatchListTimestamp]	:heavy_minus_sign:	Only include batches created strictly after this timestamp.	2026-08-20T00:00:00Z
`created_before`	Optional[components.BatchListTimestamp]	:heavy_minus_sign:	Only include batches created strictly before this timestamp.	2026-08-20T00:00:00Z
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

operations.ListBatchesResponse

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). Returns 202 with status: "validating". Poll GET /batches/{id} for progress and results. See the Batch API Quickstart.

Example Usage: chatCompletions

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", requests=[
        {
            "body": {
                "messages": [
                    {
                        "content": "Summarize ...",
                        "role": "user",
                    },
                ],
                "model": "openai/gpt-4o",
            },
            "custom_id": "req-0001",
        },
    ], completion_window="24h")

    # Handle response
    print(res)

Example Usage: messages

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", requests=[
        {
            "body": {
                "max_tokens": 1024,
                "messages": [
                    {
                        "content": "Summarize ...",
                        "role": "user",
                    },
                ],
                "model": "openai/gpt-5-nano",
            },
            "custom_id": "req-0001",
        },
    ], completion_window="24h")

    # Handle response
    print(res)

Example Usage: providerPinned

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", requests=[
        {
            "body": {
                "messages": [
                    {
                        "content": "Summarize ...",
                        "role": "user",
                    },
                ],
                "model": "google/gemini-3.6-flash",
            },
            "custom_id": "req-0001",
        },
    ], completion_window="24h")

    # Handle response
    print(res)

Example Usage: responses

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", requests=[
        {
            "body": {
                "input": [
                    {
                        "content": [
                            {
                                "text": "Summarize ...",
                                "type": "input_text",
                            },
                        ],
                        "role": "user",
                    },
                ],
                "model": "openai/gpt-4o",
            },
            "custom_id": "req-0001",
        },
    ], completion_window="24h")

    # Handle response
    print(res)

Parameters

Parameter	Type	Required	Description	Example
`endpoint`	components.Endpoint	:heavy_check_mark:	N/A
`model`	str	:heavy_check_mark:	N/A
`requests`	List[components.Request]	:heavy_check_mark:	N/A
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`completion_window`	Optional[components.BatchSubmitBodyCompletionWindow]	:heavy_minus_sign:	N/A
`provider`	OptionalNullable[components.BatchProviderPreferences]	:heavy_minus_sign:	Batch provider routing preferences. Only `provider.only` is supported.	{ “only”: [ “google-vertex” ] }
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.BatchObject

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.

Example Usage

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	:heavy_check_mark:	The batch job id returned from submit.	batch_abc123
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.BatchDeletedObject

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.

Example Usage

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	:heavy_check_mark:	The batch job id returned from submit.	batch_abc123
`http_referer`	Optional[str]	:heavy_minus_sign:	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]	:heavy_minus_sign:	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	:heavy_minus_sign:	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	:heavy_minus_sign:	Configuration to override the default retry behavior of the client.

Response

components.BatchObject

Errors

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

​Overview

​Available Operations

​list

​Example Usage

​Parameters

​Response

​Errors

​create_batches

​Example Usage: chatCompletions

​Example Usage: messages

​Example Usage: providerPinned

​Example Usage: responses

​Parameters

​Response

​Errors

​delete

​Example Usage

​Parameters

​Response

​Errors

​get_batches

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

list

Example Usage

Parameters

Response

Errors

create_batches

Example Usage: chatCompletions

Example Usage: messages

Example Usage: providerPinned

Example Usage: responses

Parameters

Response

Errors

delete

Example Usage

Parameters

Response

Errors

get_batches

Example Usage

Parameters

Response

Errors