> ## 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

**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" }
          ]
        }
      }
    ]
  }'
```

**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)
```

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

**REST**

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

**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)
```

**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

**REST**

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

**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)
```

**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

**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"
```

**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)
```

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

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