Batches

Self-hosted deployments require Enterprise Gateway v2.6.1+.

Portkey exposes Anthropic’s Message Batches API for Claude Platform on AWS through the unified OpenAI-compatible /v1/batches endpoints. All five batch operations — create, retrieve, cancel, list, and get output — are supported, enabling large asynchronous Claude jobs at 50% lower cost. Use batches for offline workloads like 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

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.

{
  "requests": [
    {
      "custom_id": "req-1",
      "params": {
        "model": "claude-sonnet-4-6",
        "max_tokens": 1024,
        "messages": [
          { "role": "user", "content": "Hello" }
        ]
      }
    }
  ]
}

Create a Batch

Python
NodeJS
REST
OpenAI Python
OpenAI NodeJS

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="@claude-platform-aws-provider"
)

batch = portkey.post(
    "/batches",
    requests=[
        {
            "custom_id": "req-1",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello"}]
            }
        }
    ]
)

print(batch)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "@claude-platform-aws-provider"
});

const batch = await portkey.post('/batches', {
    requests: [
        {
            custom_id: "req-1",
            params: {
                model: "claude-sonnet-4-6",
                max_tokens: 1024,
                messages: [{ role: "user", content: "Hello" }]
            }
        }
    ]
});

console.log(batch);

curl -X POST https://api.portkey.ai/v1/batches \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @claude-platform-aws-provider" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "custom_id": "req-1",
        "params": {
          "model": "claude-sonnet-4-6",
          "max_tokens": 1024,
          "messages": [
            { "role": "user", "content": "Hello" }
          ]
        }
      }
    ]
  }'

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="@claude-platform-aws-provider",
        api_key="PORTKEY_API_KEY"
    )
)

batch = client.post(
    "/batches",
    body={
        "requests": [
            {
                "custom_id": "req-1",
                "params": {
                    "model": "claude-sonnet-4-6",
                    "max_tokens": 1024,
                    "messages": [{"role": "user", "content": "Hello"}]
                }
            }
        ]
    },
    cast_to=object
)

print(batch)

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: "@claude-platform-aws-provider",
        apiKey: "PORTKEY_API_KEY"
    })
});

const batch = await client.post('/batches', {
    body: {
        requests: [
            {
                custom_id: "req-1",
                params: {
                    model: "claude-sonnet-4-6",
                    max_tokens: 1024,
                    messages: [{ role: "user", content: "Hello" }]
                }
            }
        ]
    }
});

console.log(batch);

Retrieve a Batch

Returns the OpenAI-compatible Batch object. Once processing completes, the response includes results_url from Anthropic.

Python
NodeJS
REST
OpenAI Python
OpenAI NodeJS

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="@claude-platform-aws-provider"
)

batch = portkey.batches.retrieve(batch_id="<batch_id>")

print(batch)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "@claude-platform-aws-provider"
});

const batch = await portkey.batches.retrieve("<batch_id>");

console.log(batch);

curl https://api.portkey.ai/v1/batches/<batch_id> \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @claude-platform-aws-provider"

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="@claude-platform-aws-provider",
        api_key="PORTKEY_API_KEY"
    )
)

batch = client.batches.retrieve("<batch_id>")

print(batch)

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: "@claude-platform-aws-provider",
        apiKey: "PORTKEY_API_KEY"
    })
});

const batch = await client.batches.retrieve("<batch_id>");

console.log(batch);

List Batches

Python
NodeJS
REST
OpenAI Python
OpenAI NodeJS

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="@claude-platform-aws-provider"
)

batches = portkey.batches.list()

print(batches)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "@claude-platform-aws-provider"
});

const batches = await portkey.batches.list();

console.log(batches);

curl https://api.portkey.ai/v1/batches \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @claude-platform-aws-provider"

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="@claude-platform-aws-provider",
        api_key="PORTKEY_API_KEY"
    )
)

batches = client.batches.list()

print(batches)

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: "@claude-platform-aws-provider",
        apiKey: "PORTKEY_API_KEY"
    })
});

const batches = await client.batches.list();

console.log(batches);

Cancel a Batch

Python
NodeJS
REST
OpenAI Python
OpenAI NodeJS

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    provider="@claude-platform-aws-provider"
)

cancelled = portkey.batches.cancel(batch_id="<batch_id>")

print(cancelled)

import Portkey from 'portkey-ai';

const portkey = new Portkey({
    apiKey: "PORTKEY_API_KEY",
    provider: "@claude-platform-aws-provider"
});

const cancelled = await portkey.batches.cancel("<batch_id>");

console.log(cancelled);

curl -X POST https://api.portkey.ai/v1/batches/<batch_id>/cancel \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @claude-platform-aws-provider"

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="@claude-platform-aws-provider",
        api_key="PORTKEY_API_KEY"
    )
)

cancelled = client.batches.cancel("<batch_id>")

print(cancelled)

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: "@claude-platform-aws-provider",
        apiKey: "PORTKEY_API_KEY"
    })
});

const cancelled = await client.batches.cancel("<batch_id>");

console.log(cancelled);

Get Batch Output

Before streaming results, Portkey retrieves the batch metadata and verifies that processing_status === 'ended'. It then fetches from Anthropic’s results_url, generating fresh SigV4-signed headers for the output URL. The response body is streamed back as JSONL in Anthropic’s native format.

REST

curl https://api.portkey.ai/v1/batches/<batch_id>/output \
  -H "x-portkey-api-key: $PORTKEY_API_KEY" \
  -H "x-portkey-provider: @claude-platform-aws-provider"

A typical output line:

{
  "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-6",
      "stop_reason": "end_turn",
      "usage": { "input_tokens": 10, "output_tokens": 12 }
    }
  }
}

Response Format

createBatch, retrieveBatch, cancelBatch, and listBatches 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 to Unix epoch seconds
Request counts mapped: succeeded → completed, errored → failed
retrieveBatch surfaces results_url from the Anthropic response when the batch has finished processing

getBatchOutput streams the raw Anthropic-native JSONL for full Claude response fidelity (content blocks, tool use, stop reasons, usage).

Ecosystem

LLM Integrations

Cloud Platforms

Guardrails

Plugins

Vector Databases

Agents

AI Apps

Libraries

Tracing Providers

MCP Clients

MCP Servers

Supported Endpoints

Request Format

Create a Batch

Retrieve a Batch

List Batches

Cancel a Batch

Get Batch Output

Response Format

See Also

​Supported Endpoints

​Request Format

​Create a Batch

​Retrieve a Batch

​List Batches

​Cancel a Batch

​Get Batch Output

​Response Format

​See Also

Supported Endpoints

Request Format

Create a Batch

Retrieve a Batch

List Batches

Cancel a Batch

Get Batch Output

Response Format

See Also