---
title: "Create a batch"
method: POST
path: "/batches"
tags: ["Batch"]
---

# Create a batch

`POST /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](https://openrouter.ai/docs/batch-quickstart).

## Request body

- BatchSubmitBody — Batch submit request body.
  - `completion_window` '24h'
  - `endpoint` '/v1/chat/completions' | '/v1/responses' | '/v1/messages' | '/v1/embeddings', required
  - `model` string, required
  - `provider` BatchProviderPreferences, nullable — Batch provider routing preferences. Only `provider.only` is supported.
    - `only` union[], nullable — List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request.
      - union
        - 'Modal' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AssemblyAI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Claude Platform on AWS' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'CoreWeave' | 'Cosine' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Databricks' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Fish Audio' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Makora' | 'Mara' | 'Mancer 2' | 'Meta' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'VoyageAI by MongoDB' | 'TypeSafe' | 'Near AI' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'Ollama' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'PrimeIntellect' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Respan' | 'Sail Research' | 'Sakana AI' | 'SambaNova' | 'ScaleDown' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tencent' | 'Tenstorrent' | 'Thinking Machines' | 'Together' | 'Unbiased' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Krea' | 'Runway' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider'
        - string
  - `requests` object[], required
    - `body` object, required — Request payload for the batch `endpoint`.
    - `custom_id` string, required

## Response `202`

Batch payload durably persisted and queued for asynchronous validation and provider submission (`status: "validating"`).

- BatchObject — unresolved $ref

## Other responses

- `400` — Malformed batch input or an unknown/incompatible batch model.
- `401` — Missing or invalid API key.
- `402` — The estimated batch cost exceeds the available balance.
- `403` — The resolved batch endpoint is blocked by account policy.
- `404` — No batch exists for the given id.
- `413` — Batch input exceeds the maximum payload size.
- `422` — The requested model variant or custom IDs violate Batch API constraints.
- `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** `31b1cd25caca` — 1 info
  - added the new `Respan` enum value to the request property `provider/only/items/anyOf[#/components/schemas/ProviderName]/`
- **2026-09-25** `024c455cb825` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/batches/post.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/7c237298ce97?raw)