Message Batching API

Relevant source files

The following files were used as context for generating this wiki page:

• betamessagebatch.go
• betamessagebatch_test.go
• messagebatch_test.go
• betamessage_test.go
• message_test.go

The Message Batching API allows users to process multiple Message creation requests asynchronously in a single batch. This system is designed for high-throughput workloads where immediate response latency is less critical than processing volume. Once a Message Batch is created, it begins processing immediately and can take up to 24 hours to complete.

The API provides a complete lifecycle for batch management, including creation, status polling, cancellation, deletion, and results retrieval. It is primarily accessed through the BetaMessageBatchService within the SDK.

Sources: betamessagebatch.go:41-48, betamessagebatch.go:210-211

API Lifecycle and Operations

The Message Batching system follows a specific asynchronous workflow where requests are submitted, processed by the system, and results are eventually made available as a downloadable file.

Batch Workflow Flowchart

The following diagram illustrates the typical lifecycle of a Message Batch from submission to results retrieval.

This diagram shows the transitions between processing states and the final availability of results.
Sources: betamessagebatch.go:41-48, betamessagebatch.go:121-125, betamessagebatch.go:264-266

Core Service Methods

The BetaMessageBatchService provides the following primary operations:

Method	HTTP Verb	Purpose
New	POST	Submits a new batch of Message creation requests.
Get	GET	Retrieves the current status and metadata of a specific batch (idempotent).
List	GET	Returns a paginated list of all Message Batches within a Workspace.
Cancel	POST	Initiates cancellation of an in-progress batch.
Delete	DELETE	Removes a finished batch; in-progress batches must be canceled first.
ResultsStreaming	GET	Streams the individual request results as a .jsonl file.

Sources: betamessagebatch.go:49-146

Data Structures and Models

The API uses several structured types to represent the batch, its constituent requests, and the final results.

BetaMessageBatch Object

The BetaMessageBatch struct represents the top-level batch object containing metadata and processing status.

Field	Type	Description
ID	string	Unique identifier for the batch.
ProcessingStatus	string	Status: "in_progress", "canceling", or "ended".
RequestCounts	struct	Tallies of succeeded, errored, canceled, processing, and expired requests.
ResultsURL	string	URL to the .jsonl results file (available once status is "ended").
CreatedAt	time.Time	Timestamp of batch creation.
ExpiresAt	time.Time	Timestamp 24 hours after creation when the batch expires.

Sources: betamessagebatch.go:210-255

Individual Request and Response

Each batch consists of multiple requests, each assigned a CustomID by the developer to correlate results.

The relationship between input requests and individual results.
Sources: betamessagebatch.go:343-353, betamessagebatch.go:303-316, betamessagebatch.go:384-403

Request Configuration and Parameters

Individual requests within a batch support most standard Messages API parameters, such as Model, MaxTokens, System prompts, and Tools.

Batch Creation Parameters

The BetaMessageBatchNewParamsRequestParams struct defines the configuration for each message in the batch. Key parameters include:

• Model: The Claude model to be used (e.g., ClaudeOpus4_6).
• MaxTokens: Absolute maximum tokens to generate.
• StopSequences: Custom text sequences that trigger generation halt.
• Thinking: Configuration for extended thinking process (requires minimum 1,024 tokens).
• Betas: Headers specifying beta versions, specifically message-batches-2024-09-24 for this API.

Sources: betamessagebatch.go:49-55, betamessagebatch.go:406-440, betamessagebatch_test.go:47-152

Results Retrieval

Results are retrieved via ResultsStreaming, which returns a jsonl.Stream. Each line is an independent JSON object containing the result of one request.

func (r *BetaMessageBatchService) ResultsStreaming(
    ctx context.Context, 
    messageBatchID string, 
    query BetaMessageBatchResultsParams, 
    opts ...option.RequestOption,
) (stream *jsonl.Stream[BetaMessageBatchIndividualResponse])

Sources: betamessagebatch.go:141-160

Testing and Implementation Examples

The SDK includes comprehensive tests for verifying batch operations, including optional parameters like Metadata, MCPServers, and ToolChoice.

Test Example: Batch Creation

The test suite demonstrates submitting a batch with complex parameters, including citations and ephemeral cache control.

_, err := client.Beta.Messages.Batches.New(context.TODO(), anthropic.BetaMessageBatchNewParams{
    Requests: []anthropic.BetaMessageBatchNewParamsRequest{{
        CustomID: "my-custom-id-1",
        Params: anthropic.BetaMessageBatchNewParamsRequestParams{
            MaxTokens: 1024,
            Messages: []anthropic.BetaMessageParam{{
                Role: anthropic.BetaMessageParamRoleUser,
                Content: []anthropic.BetaContentBlockParamUnion{{
                    OfText: &anthropic.BetaTextBlockParam{Text: "x"},
                }},
            }},
            Model: anthropic.ModelClaudeOpus4_6,
        },
    }},
    Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaMessageBatches2024_09_24},
})

Sources: betamessagebatch_test.go:27-164, messagebatch_test.go:25-103

Summary

The Message Batching API provides a robust mechanism for handling large-scale asynchronous message generation. By utilizing the BetaMessageBatchService, developers can manage the lifecycle of batches and efficiently retrieve results via JSONL streaming. The architecture ensures idempotency for status checks and supports standard Message features like tool use and extended thinking within individual batch items.

Sources: betamessagebatch.go:41-48, betamessagebatch.go:210-255