Create a Message Batch

POST /v1/messages/batches?beta=true

Copy endpoint

https://api.anthropic.com

Send a batch of Message creation requests.

The Message Batches API can be used to process multiple Messages API requests at once. Once a Message Batch is created, it begins processing immediately. Batches can take up to 24 hours to complete.

Learn more about the Message Batches API in our user guide

Parameters

header Header Parameters

Name	Type
`anthropic-beta` Optional header to specify the beta version(s) you want to use. To use multiple betas, use a comma separated list like `beta1,beta2` or specify the header multiple times for each beta.	string
`anthropic-version` The version of the Claude API you want to use. Read more about versioning and our version history here.	string

Request Body

application/json required

interface BetaCreateMessageBatchParams {
requests:

BetaMessageBatchIndividualRequestParams

interface BetaMessageBatchIndividualRequestParams {
custom_id: string;
params: BetaCreateMessageParams;
}

[];
}

Responses

200 application/json

Successful Response

interface BetaMessageBatch {
archived_at: string | null;
cancel_initiated_at: string | null;
created_at: string;
ended_at: string | null;
expires_at: string;
id: string;
processing_status: "in_progress" | "canceling" | "ended";
request_counts:

BetaRequestCounts

interface BetaRequestCounts {
canceled: number;
errored: number;
expired: number;
processing: number;
succeeded: number;
}

;
results_url: string | null;
type: "message_batch";
}

Client Errors

4XX application/json

Error response.

See our errors documentation for more details.

interface BetaErrorResponse {
error:

BetaInvalidRequestError

interface BetaInvalidRequestError {
message: string;
type: "invalid_request_error";
}

BetaAuthenticationError

interface BetaAuthenticationError {
message: string;
type: "authentication_error";
}

BetaBillingError

interface BetaBillingError {
message: string;
type: "billing_error";
}

BetaPermissionError

interface BetaPermissionError {
message: string;
type: "permission_error";
}

BetaNotFoundError

interface BetaNotFoundError {
message: string;
type: "not_found_error";
}

BetaRateLimitError

interface BetaRateLimitError {
message: string;
type: "rate_limit_error";
}

BetaGatewayTimeoutError

interface BetaGatewayTimeoutError {
message: string;
type: "timeout_error";
}

BetaAPIError

interface BetaAPIError {
message: string;
type: "api_error";
}

BetaOverloadedError

interface BetaOverloadedError {
message: string;
type: "overloaded_error";
}

;
request_id: string | null;
type: "error";
}