> ## Documentation Index > Fetch the complete documentation index at: https://docs.portkey.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Batches > Run asynchronous batch jobs on Anthropic's Claude models through Portkey's unified /v1/batches API > [!NOTE] > > Self-hosted deployments require **Enterprise Gateway v2.6.1+**. Portkey exposes Anthropic's [Message Batches API](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing) through the unified OpenAI-compatible `/v1/batches` endpoints. All five batch operations — create, retrieve, cancel, list, and get output — are supported, so you can run large, asynchronous Claude jobs at 50% lower cost without leaving the Portkey gateway. Use batches when you need to run large jobs offline — e.g. nightly evals, bulk summarization, or dataset grading. ## Supported Endpoints | Gateway Endpoint | Anthropic Upstream | Operation | | - | - | - | | `POST /v1/batches` | `POST /v1/messages/batches` | Create a batch | | `GET /v1/batches/{batch_id}` | `GET /v1/messages/batches/{batch_id}` | Retrieve a batch | | `POST /v1/batches/{batch_id}/cancel` | `POST /v1/messages/batches/{batch_id}/cancel` | Cancel a batch | | `GET /v1/batches` | `GET /v1/messages/batches` | List batches | | `GET /v1/batches/{batch_id}/output` | Streams from `results_url` | Get batch output | ## Request Format > [!NOTE] > > Unlike OpenAI's file-based batches, Anthropic batch creation uses an inline `requests[]` array — there is no `input_file_id`. Each item carries a `custom_id` and a `params` object containing the standard Messages API payload. ```json theme={"system"} { "requests": [ { "custom_id": "req-1", "params": { "model": "claude-sonnet-4-20250514", "max_tokens": 1024, "messages": [ { "role": "user", "content": "Hello" } ] } } ] } ``` ## Create a Batch > [tab] Python > > ```python theme={"system"} > from portkey_ai import Portkey > > portkey = Portkey( > api_key="PORTKEY_API_KEY", > provider="@anthropic" > ) > > batch = portkey.post( > "/batches", > requests=[ > { > "custom_id": "req-1", > "params": { > "model": "claude-sonnet-4-20250514", > "max_tokens": 1024, > "messages": [{"role": "user", "content": "Hello"}] > } > } > ] > ) > > print(batch) > ``` > [tab] NodeJS > > ```js theme={"system"} > import Portkey from 'portkey-ai'; > > const portkey = new Portkey({ > apiKey: "PORTKEY_API_KEY", > provider: "@anthropic" > }); > > const batch = await portkey.post('/batches', { > requests: [ > { > custom_id: "req-1", > params: { > model: "claude-sonnet-4-20250514", > max_tokens: 1024, > messages: [{ role: "user", content: "Hello" }] > } > } > ] > }); > > console.log(batch); > ``` > [tab] REST > > ```sh theme={"system"} > curl -X POST https://api.portkey.ai/v1/batches \ > -H "x-portkey-api-key: $PORTKEY_API_KEY" \ > -H "x-portkey-provider: @anthropic" \ > -H "Content-Type: application/json" \ > -d '{ > "requests": [ > { > "custom_id": "req-1", > "params": { > "model": "claude-sonnet-4-20250514", > "max_tokens": 1024, > "messages": [ > { "role": "user", "content": "Hello" } > ] > } > } > ] > }' > ``` > [tab] OpenAI Python > > ```python theme={"system"} > from openai import OpenAI > from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders > > client = OpenAI( > api_key="PORTKEY_API_KEY", > base_url=PORTKEY_GATEWAY_URL, > default_headers=createHeaders( > provider="@anthropic", > api_key="PORTKEY_API_KEY" > ) > ) > > batch = client.post( > "/batches", > body={ > "requests": [ > { > "custom_id": "req-1", > "params": { > "model": "claude-sonnet-4-20250514", > "max_tokens": 1024, > "messages": [{"role": "user", "content": "Hello"}] > } > } > ] > }, > cast_to=object > ) > > print(batch) > ``` > [tab] OpenAI NodeJS > > ```js theme={"system"} > import OpenAI from 'openai'; > import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai'; > > const client = new OpenAI({ > apiKey: "PORTKEY_API_KEY", > baseURL: PORTKEY_GATEWAY_URL, > defaultHeaders: createHeaders({ > provider: "@anthropic", > apiKey: "PORTKEY_API_KEY" > }) > }); > > const batch = await client.post('/batches', { > body: { > requests: [ > { > custom_id: "req-1", > params: { > model: "claude-sonnet-4-20250514", > max_tokens: 1024, > messages: [{ role: "user", content: "Hello" }] > } > } > ] > } > }); > > console.log(batch); > ``` ## Retrieve a Batch Retrieving a batch returns the OpenAI-compatible Batch object. Once processing completes, the response additionally includes `results_url` pulled from Anthropic so you can stream outputs. > [tab] Python > > ```python theme={"system"} > from portkey_ai import Portkey > > portkey = Portkey( > api_key="PORTKEY_API_KEY", > provider="@anthropic" > ) > > batch = portkey.batches.retrieve(batch_id="") > > print(batch) > ``` > [tab] NodeJS > > ```js theme={"system"} > import Portkey from 'portkey-ai'; > > const portkey = new Portkey({ > apiKey: "PORTKEY_API_KEY", > provider: "@anthropic" > }); > > const batch = await portkey.batches.retrieve(""); > > console.log(batch); > ``` > [tab] REST > > ```sh theme={"system"} > curl https://api.portkey.ai/v1/batches/ \ > -H "x-portkey-api-key: $PORTKEY_API_KEY" \ > -H "x-portkey-provider: @anthropic" > ``` > [tab] OpenAI Python > > ```python theme={"system"} > from openai import OpenAI > from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders > > client = OpenAI( > api_key="PORTKEY_API_KEY", > base_url=PORTKEY_GATEWAY_URL, > default_headers=createHeaders( > provider="@anthropic", > api_key="PORTKEY_API_KEY" > ) > ) > > batch = client.batches.retrieve("") > > print(batch) > ``` > [tab] OpenAI NodeJS > > ```js theme={"system"} > import OpenAI from 'openai'; > import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai'; > > const client = new OpenAI({ > apiKey: "PORTKEY_API_KEY", > baseURL: PORTKEY_GATEWAY_URL, > defaultHeaders: createHeaders({ > provider: "@anthropic", > apiKey: "PORTKEY_API_KEY" > }) > }); > > const batch = await client.batches.retrieve(""); > > console.log(batch); > ``` ## List Batches > [tab] Python > > ```python theme={"system"} > from portkey_ai import Portkey > > portkey = Portkey( > api_key="PORTKEY_API_KEY", > provider="@anthropic" > ) > > batches = portkey.batches.list() > > print(batches) > ``` > [tab] NodeJS > > ```js theme={"system"} > import Portkey from 'portkey-ai'; > > const portkey = new Portkey({ > apiKey: "PORTKEY_API_KEY", > provider: "@anthropic" > }); > > const batches = await portkey.batches.list(); > > console.log(batches); > ``` > [tab] REST > > ```sh theme={"system"} > curl https://api.portkey.ai/v1/batches \ > -H "x-portkey-api-key: $PORTKEY_API_KEY" \ > -H "x-portkey-provider: @anthropic" > ``` > [tab] OpenAI Python > > ```python theme={"system"} > from openai import OpenAI > from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders > > client = OpenAI( > api_key="PORTKEY_API_KEY", > base_url=PORTKEY_GATEWAY_URL, > default_headers=createHeaders( > provider="@anthropic", > api_key="PORTKEY_API_KEY" > ) > ) > > batches = client.batches.list() > > print(batches) > ``` > [tab] OpenAI NodeJS > > ```js theme={"system"} > import OpenAI from 'openai'; > import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai'; > > const client = new OpenAI({ > apiKey: "PORTKEY_API_KEY", > baseURL: PORTKEY_GATEWAY_URL, > defaultHeaders: createHeaders({ > provider: "@anthropic", > apiKey: "PORTKEY_API_KEY" > }) > }); > > const batches = await client.batches.list(); > > console.log(batches); > ``` ## Cancel a Batch > [tab] Python > > ```python theme={"system"} > from portkey_ai import Portkey > > portkey = Portkey( > api_key="PORTKEY_API_KEY", > provider="@anthropic" > ) > > cancelled = portkey.batches.cancel(batch_id="") > > print(cancelled) > ``` > [tab] NodeJS > > ```js theme={"system"} > import Portkey from 'portkey-ai'; > > const portkey = new Portkey({ > apiKey: "PORTKEY_API_KEY", > provider: "@anthropic" > }); > > const cancelled = await portkey.batches.cancel(""); > > console.log(cancelled); > ``` > [tab] REST > > ```sh theme={"system"} > curl -X POST https://api.portkey.ai/v1/batches//cancel \ > -H "x-portkey-api-key: $PORTKEY_API_KEY" \ > -H "x-portkey-provider: @anthropic" > ``` > [tab] OpenAI Python > > ```python theme={"system"} > from openai import OpenAI > from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders > > client = OpenAI( > api_key="PORTKEY_API_KEY", > base_url=PORTKEY_GATEWAY_URL, > default_headers=createHeaders( > provider="@anthropic", > api_key="PORTKEY_API_KEY" > ) > ) > > cancelled = client.batches.cancel("") > > print(cancelled) > ``` > [tab] OpenAI NodeJS > > ```js theme={"system"} > import OpenAI from 'openai'; > import { PORTKEY_GATEWAY_URL, createHeaders } from 'portkey-ai'; > > const client = new OpenAI({ > apiKey: "PORTKEY_API_KEY", > baseURL: PORTKEY_GATEWAY_URL, > defaultHeaders: createHeaders({ > provider: "@anthropic", > apiKey: "PORTKEY_API_KEY" > }) > }); > > const cancelled = await client.batches.cancel(""); > > console.log(cancelled); > ``` ## Get Batch Output > [!NOTE] > > Before streaming results, Portkey retrieves the batch metadata and verifies that `processing_status === 'ended'`. It then fetches from Anthropic's `results_url`, falling back to `/messages/batches/{batch_id}/results` if the URL is unavailable. The response body is streamed back as JSONL in Anthropic's native format by default. > [tab] REST > > ```sh theme={"system"} > curl https://api.portkey.ai/v1/batches//output \ > -H "x-portkey-api-key: $PORTKEY_API_KEY" \ > -H "x-portkey-provider: @anthropic" > ``` A typical output line looks like: ```json theme={"system"} { "custom_id": "req-1", "result": { "type": "succeeded", "message": { "id": "msg_01XYZ...", "type": "message", "role": "assistant", "content": [{ "type": "text", "text": "Hello! How can I help?" }], "model": "claude-sonnet-4-20250514", "stop_reason": "end_turn", "usage": { "input_tokens": 10, "output_tokens": 12 } } } } ``` ## Response Format `createBatch`, `retrieveBatch`, `cancelBatch`, and `listBatches` always return the OpenAI Batch shape so existing OpenAI tooling works unchanged: * `object: "batch"` and `endpoint: "/v1/batches"` on every batch record. * `status` values normalized to OpenAI-compatible strings (`validating`, `in_progress`, `finalizing`, `completed`, `failed`, `cancelling`, `cancelled`, `expired`). * Timestamps converted from Anthropic's ISO 8601 format to Unix epoch seconds. * Request counts mapped: `succeeded → completed`, `errored → failed`. * `retrieveBatch` additionally surfaces `results_url` from the Anthropic response when the batch has finished processing. `getBatchOutput` is the exception — it streams the raw Anthropic-native JSONL so you get per-request `message` objects with full Claude response fidelity (content blocks, tool use, stop reasons, usage). ## See Also * [Unified Batch Guide](https://docs.portkey.ai/docs/product/ai-gateway/batches.md) * [Anthropic integration overview](https://docs.portkey.ai/docs/integrations/llms/anthropic.md) * [Anthropic Message Batches API reference](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing) *** > [card] [Portkey is now PRISMA AIRS AI Gateway. See it in action.](https://www.paloaltonetworks.in/ai-security/ai-gateway?utm_source=portkey\&utm_medium=referral\&utm_campaign=prisma_airs\&utm_content=docs_nav#contact) > > Contact Us ## Related topics - [Batches](https://docs.portkey.ai/docs/integrations/llms/claude-platform-aws/batches.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.