ANanthropics

Create a Message Batch

Changed on

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

post/v1/messages/batches

Request

  • Base URL
    https://api.anthropic.com
  • Auth
    none declared

Headers

anthropic-versionstring

The version of the Claude API you want to use.

Read more about versioning and our version history here.

anthropic-user-profile-idstring

The user profile ID to attribute the requests in this batch to. Use when acting on behalf of a party other than your organization. Applies to every request in the batch; an individual request whose user_profile_id body field conflicts with this header is errored.

anthropic-workspace-idstring

Optional header to select the Workspace for this request. The value is a Workspace ID (for example, wrkspc_011CZkZaBF1tNoB5wlCeusgy).

Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace.

Request body

Example request

{
  "requests": [
    {
      "custom_id": "my-custom-id-1",
      "params": {
        "max_tokens": 1024,
        "messages": [
          {
            "content": "Hello, world",
            "role": "user"
          }
        ],
        "model": "claude-opus-5-5"
      }
    }
  ]
}

Response

Successful Response

archived_atstring date-time nullable required

RFC 3339 datetime string representing the time at which the Message Batch was archived and its results became unavailable.

cancel_initiated_atstring date-time nullable required

RFC 3339 datetime string representing the time at which cancellation was initiated for the Message Batch. Specified only if cancellation was initiated.

created_atstring date-time required

RFC 3339 datetime string representing the time at which the Message Batch was created.

ended_atstring date-time nullable required

RFC 3339 datetime string representing the time at which processing for the Message Batch ended. Specified only once processing ends.

Processing ends when every request in a Message Batch has either succeeded, errored, canceled, or expired.

expires_atstring date-time required

RFC 3339 datetime string representing the time at which the Message Batch will expire and end processing, which is 24 hours after creation.

idstring required

Unique object identifier.

The format and length of IDs may change over time.

processing_status'in_progress' | 'canceling' | 'ended' required

Processing status of the Message Batch.

results_urlstring nullable required

URL to a .jsonl file containing the results of the Message Batch requests. Specified only once processing ends.

Results in the file are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

type'message_batch' required

Object type.

For Message Batches, this is always "message_batch".

Example response

{
  "archived_at": "2024-08-20T18:37:24.100435Z",
  "cancel_initiated_at": "2024-08-20T18:37:24.100435Z",
  "created_at": "2024-08-20T18:37:24.100435Z",
  "ended_at": "2024-08-20T18:37:24.100435Z",
  "expires_at": "2024-08-20T18:37:24.100435Z",
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "processing_status": "in_progress",
  "request_counts": {
    "canceled": 10,
    "errored": 30,
    "expired": 10,
    "processing": 100,
    "succeeded": 50
  },
  "results_url": "https://api.anthropic.com/v1/messages/batches/msgbatch_013Zva2CMHLNnXjNJJKqJ2EF/results"
}

Changes

  • 94c83daca660Revision changes
    • breaking

      the //// request property type changed from object to no type

    • warning

      removed the request property /////

    • warning

      removed the request property /////

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • warning

      removed the request property ///

    • info

      added assistant system user discriminator mapping keys to the //// request property

    • info

      added to the //// request property oneOf list

  • 569b1fb6ea2eRevision changes
    • info

      added the new optional request property ///