> ## 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 Prisma AIRS AI Gateway's unified /v1/batches API

> [!NOTE]
>
> Hybrid deployments require **Enterprise Gateway v2.6.1+**.

The AI Gateway 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 AI 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] REST
>
> ```sh theme={"system"}
> curl -X POST https://aigw.portkey.ai/v1/batches \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "requests": [
>       {
>         "custom_id": "req-1",
>         "params": {
>           "model": "@anthropic/claude-sonnet-4-20250514",
>           "max_tokens": 1024,
>           "messages": [
>             { "role": "user", "content": "Hello" }
>           ]
>         }
>       }
>     ]
>   }'
> ```

> [tab] OpenAI Python
>
> ```python theme={"system"}
> from openai import OpenAI
>
> client = OpenAI(
>     api_key="PORTKEY_API_KEY",
>     base_url="https://aigw.portkey.ai/v1"
> )
>
> batch = client.post(
>     "/batches",
>     body={
>         "requests": [
>             {
>                 "custom_id": "req-1",
>                 "params": {
>                     "model": "@anthropic/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';
>
> const client = new OpenAI({
>     apiKey: "PORTKEY_API_KEY",
>     baseURL: "https://aigw.portkey.ai/v1"
> });
>
> const batch = await client.post('/batches', {
>     body: {
>         requests: [
>             {
>                 custom_id: "req-1",
>                 params: {
>                     model: "@anthropic/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] REST
>
> ```sh theme={"system"}
> curl https://aigw.portkey.ai/v1/batches/<batch_id> \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @anthropic"
> ```

> [tab] OpenAI Python
>
> ```python theme={"system"}
> from openai import OpenAI
>
> client = OpenAI(
>     api_key="PORTKEY_API_KEY",
>     base_url="https://aigw.portkey.ai/v1",
>     default_headers={"x-portkey-provider": "@anthropic"}
> )
>
> batch = client.batches.retrieve("<batch_id>")
>
> print(batch)
> ```

> [tab] OpenAI NodeJS
>
> ```js theme={"system"}
> import OpenAI from 'openai';
>
> const client = new OpenAI({
>     apiKey: "PORTKEY_API_KEY",
>     baseURL: "https://aigw.portkey.ai/v1",
>     defaultHeaders: { "x-portkey-provider": "@anthropic" }
> });
>
> const batch = await client.batches.retrieve("<batch_id>");
>
> console.log(batch);
> ```

## List Batches

> [tab] REST
>
> ```sh theme={"system"}
> curl https://aigw.portkey.ai/v1/batches \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @anthropic"
> ```

> [tab] OpenAI Python
>
> ```python theme={"system"}
> from openai import OpenAI
>
> client = OpenAI(
>     api_key="PORTKEY_API_KEY",
>     base_url="https://aigw.portkey.ai/v1",
>     default_headers={"x-portkey-provider": "@anthropic"}
> )
>
> batches = client.batches.list()
>
> print(batches)
> ```

> [tab] OpenAI NodeJS
>
> ```js theme={"system"}
> import OpenAI from 'openai';
>
> const client = new OpenAI({
>     apiKey: "PORTKEY_API_KEY",
>     baseURL: "https://aigw.portkey.ai/v1",
>     defaultHeaders: { "x-portkey-provider": "@anthropic" }
> });
>
> const batches = await client.batches.list();
>
> console.log(batches);
> ```

## Cancel a Batch

> [tab] REST
>
> ```sh theme={"system"}
> curl -X POST https://aigw.portkey.ai/v1/batches/<batch_id>/cancel \
>   -H "Authorization: Bearer $PORTKEY_API_KEY" \
>   -H "x-portkey-provider: @anthropic"
> ```

> [tab] OpenAI Python
>
> ```python theme={"system"}
> from openai import OpenAI
>
> client = OpenAI(
>     api_key="PORTKEY_API_KEY",
>     base_url="https://aigw.portkey.ai/v1",
>     default_headers={"x-portkey-provider": "@anthropic"}
> )
>
> cancelled = client.batches.cancel("<batch_id>")
>
> print(cancelled)
> ```

> [tab] OpenAI NodeJS
>
> ```js theme={"system"}
> import OpenAI from 'openai';
>
> const client = new OpenAI({
>     apiKey: "PORTKEY_API_KEY",
>     baseURL: "https://aigw.portkey.ai/v1",
>     defaultHeaders: { "x-portkey-provider": "@anthropic" }
> });
>
> const cancelled = await client.batches.cancel("<batch_id>");
>
> console.log(cancelled);
> ```

## Get Batch Output

> [!NOTE]
>
> Before streaming results, the AI Gateway 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://aigw.portkey.ai/v1/batches/<batch_id>/output \
>   -H "Authorization: Bearer $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/aigw/product/ai-gateway/batches.md)
* [Anthropic integration overview](https://docs.portkey.ai/docs/aigw/integrations/llms/anthropic.md)
* [Anthropic Message Batches API reference](https://docs.anthropic.com/en/docs/build-with-claude/batch-processing)


## Related topics

- [Batches](https://docs.portkey.ai/docs/aigw/integrations/llms/claude-platform-aws/batches.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.