---
title: "List batches"
method: GET
path: "/batches"
tags: ["Batch"]
---

# List batches

`GET /batches`

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).

## Query parameters

- `limit` integer — Maximum number of batches to return, from 1 through 100.
- `after` string — Batch id from the previous page's `last_id`.
- `status` BatchListStatus[] — Repeat this parameter to include more than one status.
- `created_after` union — Only include batches created strictly after this timestamp.
  - string
  - string, date
  - string, date-time
- `created_before` union
  - string — Only include batches created strictly before this timestamp.
  - string, date — Only include batches created strictly before this timestamp.
  - string, date-time — Only include batches created strictly before this timestamp.

## Response `200`

A newest-first page of batches.

- BatchListResponse — A newest-first page of metadata-only batch objects.
  - `data` BatchListItem[], required
    - `completion_window` '24h', required
    - `created_at` integer, required
    - `endpoint` string, required
    - `error` object, nullable, required
      - `message` string, required
    - `finalized_at` integer, nullable, required
    - `id` string, required
    - `model` string, required
    - `object` 'batch', required
    - `request_counts` object, required
      - `completed` integer, required
      - `failed` integer, required
      - `total` integer, required
    - `results` unknown, required
    - `status` 'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled', required
    - `usage` object, nullable, required
      - `cache_creation` AnthropicCacheCreation, nullable
        - `ephemeral_1h_input_tokens` integer, required
        - `ephemeral_5m_input_tokens` integer, required
      - `completion_tokens` integer, required — The tokens generated
      - `completion_tokens_details` object, nullable
        - `audio_tokens` integer, nullable — Tokens generated by the model for audio output.
        - `image_tokens` integer, nullable — Tokens generated by the model for image output.
        - `reasoning_tokens` integer, nullable — Tokens generated by the model for reasoning.
      - `cost` number, double, nullable — Cost of the completion
      - `cost_details` CostDetails, nullable — Breakdown of upstream inference costs
        - `server_tool_cost` number, double, nullable — Metered server-tool execution cost (for example, shell sandbox time) billed for this request, in USD. Matches the billed checkpoint and settlement amounts exactly. 0 when a metered server tool ran but settled at zero dollars; absent when no metered server tool ran.
        - `upstream_inference_completions_cost` number, double, required
        - `upstream_inference_cost` number, double, nullable
        - `upstream_inference_prompt_cost` number, double, required
      - `is_byok` boolean — Whether a request was made using a Bring Your Own Key configuration
      - `iterations` AnthropicUsageIteration[], nullable
        - union
          - AnthropicCompactionUsageIteration
            - `cache_creation` AnthropicIterationCacheCreation, nullable
              - …
            - `cache_creation_input_tokens` integer
            - `cache_read_input_tokens` integer
            - `input_tokens` integer
            - `output_tokens` integer
            - `type` 'compaction', required
          - AnthropicMessageUsageIteration
            - `cache_creation` AnthropicIterationCacheCreation, nullable
              - …
            - `cache_creation_input_tokens` integer
            - `cache_read_input_tokens` integer
            - `input_tokens` integer
            - `output_tokens` integer
            - `model` string
            - `type` 'message', required
          - AnthropicAdvisorMessageUsageIteration
            - `cache_creation` AnthropicIterationCacheCreation, nullable
              - …
            - `cache_creation_input_tokens` integer
            - `cache_read_input_tokens` integer
            - `input_tokens` integer
            - `output_tokens` integer
            - `model` string, required
            - `type` 'advisor_message', required
          - AnthropicUnknownUsageIteration
            - `cache_creation` AnthropicIterationCacheCreation, nullable
              - …
            - `cache_creation_input_tokens` integer
            - `cache_read_input_tokens` integer
            - `input_tokens` integer
            - `output_tokens` integer
            - `type` string, required
      - `prompt_tokens` integer, required — Including images, input audio, and tools if any
      - `prompt_tokens_details` object, nullable — Breakdown of tokens used in the prompt.
        - `audio_tokens` integer, nullable — Tokens used for input audio.
        - `cache_write_tokens` integer, nullable — Tokens written to cache. Only returned for models with explicit caching and cache write pricing.
        - `cached_tokens` integer, nullable — Tokens cached by the endpoint.
        - `file_tokens` integer, nullable — Tokens used for input files/documents.
        - `video_tokens` integer, nullable — Tokens used for input video.
      - `server_tool_use` object, nullable — Usage for server-side tool execution (e.g., web search)
        - `tool_calls_executed` integer, nullable — Number of OpenRouter server tool calls that executed and produced a result.
        - `tool_calls_requested` integer, nullable — Total number of OpenRouter server-orchestrated tool calls the model requested, across all tool types. Provider-native tools (e.g. native web search) are not counted here.
        - `web_search_requests` integer, nullable — Number of web searches performed by server-side tools. For server-orchestrated tool calls a web search is also counted in tool_calls_requested; provider-native web search may report web_search_requests only. Do not sum the two.
      - `service_tier` string, nullable — The service tier used by the upstream provider for this request
      - `speed` 'fast' | 'standard' | 'null', nullable
      - `total_tokens` integer, required — Sum of the above two fields
  - `first_id` string, nullable, required
  - `has_more` boolean, required
  - `last_id` string, nullable, required
  - `object` 'list', required

## Other responses

- `400` — Malformed or unsupported batch list query parameters.
- `401` — Missing or invalid API key.
- `429` — Batch API rate limit exceeded for the billable entity.
- `500` — Unexpected error in the ingress or upstream batch-api.
- `502` — The batch service is unavailable, or an upstream provider operation failed, including batch or file cleanup.

## Changes

- **2026-09-25** `024c455cb825` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/batches/get.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openrouterteam/apis/openrouter-api/revisions/31b1cd25caca?raw)