Message Batches Reference

Purpose and Scope

Message Batches are the SDK surface for submitting many Messages API requests as one asynchronous unit. Instead of awaiting each individual Claude response in a foreground loop, a caller creates a batch containing request objects, tracks the batch state, and later reads individual results. This reference is for developers wiring production batch jobs, backfills, evaluations, or queue workers against @anthropic-ai/sdk. It explains the stable client.messages.batches resource, the beta mirror at client.beta.messages.batches, and the exported TypeScript result types that make result handling explicit.

Sources: tests/api-resources/messages/batches.test.ts, tests/api-resources/beta/messages/batches.test.ts, src/resources/messages/index.ts, api.md

The SDK treats a batch request as a list of Message creation requests. Each item has a developer-provided custom_id and a params object shaped like a normal Messages API create call. Official API docs emphasize that custom_id is the stable key for matching returned results to submitted work, because batch results may not be emitted in request order. The generated stable tests show the minimum request: max_tokens, one user message, and a model such as claude-opus-4-6. The same test also verifies the SDK response wrapper behavior for raw and parsed responses.

The batch lifecycle is asynchronous. After creation, the service starts processing immediately, can take up to 24 hours, and exposes status and request-count fields so callers can poll or decide when to fetch results. The official cancel endpoint documents three processing statuses: in_progress, canceling, and ended. Cancellation is best understood as a state transition, not an immediate guarantee that every unfinished item is canceled; in-progress non-interruptible requests may still finish. For precise job accounting, inspect individual batch results rather than assuming the top-level canceled count answers every operational question.

Relevant Source Files

• tests/api-resources/messages/batches.test.ts - Generated stable-resource tests that exercise client.messages.batches.create(...), retrieve(...), response wrapper helpers, required create parameters, and a broad optional parameter set.
• tests/api-resources/beta/messages/batches.test.ts - Generated beta-resource tests that mirror the batch resource under client.beta.messages.batches and demonstrate beta-only request fields such as MCP servers, context management, fallback configuration, and richer container configuration.
• src/resources/messages/index.ts - Public export barrel for the messages namespace, including Batches, MessageBatch, result variants, request-count types, create/list params, and MessageBatchesPage.
• api.md - Generated API reference source for the SDK surface covered by this page.

Sources: tests/api-resources/messages/batches.test.ts, tests/api-resources/beta/messages/batches.test.ts, src/resources/messages/index.ts, api.md

Public Resource Shape

The stable entry point is client.messages.batches. The generated export barrel makes the batch resource and its public types part of the messages namespace by exporting Batches, DeletedMessageBatch, MessageBatch, MessageBatchRequestCounts, MessageBatchIndividualResponse, and the result union members MessageBatchSucceededResult, MessageBatchErroredResult, MessageBatchCanceledResult, and MessageBatchExpiredResult. It also exports BatchCreateParams, BatchListParams, and MessageBatchesPage, which are the main compile-time contracts a TypeScript integration will see when creating, listing, and paging through batches.

Sources: src/resources/messages/index.ts

The generated tests show that resource calls return an SDK response promise with multiple consumption modes. In the stable create test, client.messages.batches.create(...) can be awaited to get parsed data, .asResponse() returns the underlying Response, and .withResponse() returns both the parsed data and raw response. This is important for batch workflows because production systems often need both the typed batch object and transport metadata, such as headers or status, for logging, rate-limit diagnostics, request IDs, or internal retry accounting.

Sources: tests/api-resources/messages/batches.test.ts

The beta entry point is client.beta.messages.batches. It follows the same high-level shape as the stable resource but accepts beta headers and beta request fields. The beta generated test demonstrates fields that are not just syntactic extras: context_management can request tool-use clearing behavior, mcp_servers configures remote MCP tool access, fallbacks and fallback_credit_token support model fallback behavior, and container configuration can include Anthropic skills. Use the stable namespace for generally available batch work, and the beta namespace when your request relies on beta capabilities documented for the corresponding API version.

Sources: tests/api-resources/beta/messages/batches.test.ts, api.md

Compact Method and Type Reference

Sources: tests/api-resources/messages/batches.test.ts, tests/api-resources/beta/messages/batches.test.ts, src/resources/messages/index.ts, api.md

The table is intentionally compact, but the design implication is significant: code that creates a batch should store the returned batch ID and the original custom_id values. Code that consumes results should not rely on array position. A robust worker treats custom_id as the join key back to internal records, narrows the result variant, and records terminal status separately from the top-level batch status. The exported result variant types exist so callers can make that terminal-state logic explicit instead of treating every result as a successful Message response.

Creating Batches

A minimal stable create call contains a single requests array with at least one request object. Each request has a custom_id and a Messages API params payload. The generated stable test uses max_tokens: 1024, a user message with content: 'Hello, world', and model: 'claude-opus-4-6'. In real batch jobs, create a unique custom_id for each unit of work, such as a database primary key or evaluation case ID. That value is the safest way to reconcile returned results with application state.

Sources: tests/api-resources/messages/batches.test.ts

import Anthropic from '@anthropic-ai/sdk';
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: 'ticket-123',
      params: {
        model: 'claude-opus-4-6',
        max_tokens: 1024,
        messages: [{ role: 'user', content: 'Summarize this support ticket.' }],
      },
    },
  ],
});

The optional stable create surface is broad because each batch item embeds a Messages API request. The stable generated test includes examples for cache control, container, inference geography, metadata, structured output_config, service tier, stop sequences, system blocks with citations, temperature, thinking, tool choice, tool definitions, top_k, and top_p. It also shows a batch-level user_profile_id value. Treat these options as per-request Message configuration unless the field is explicitly batch-level. If you already have a validated Messages create payload, it is usually the right starting point for each batch item.

Sources: tests/api-resources/messages/batches.test.ts

Retrieving, Canceling, and Reading Results

Retrieval is the polling primitive. The generated stable test calls client.messages.batches.retrieve('message_batch_id') and verifies the same parsed/raw response consumption modes as create. Polling code should read the returned MessageBatch metadata, inspect processing_status, and use request_counts to decide whether to continue waiting, alert, cancel, or fetch available results. The official API docs define processing as complete only after every individual request has succeeded, errored, canceled, or expired, so a top-level ended state still requires per-result inspection before application records are complete.

Sources: tests/api-resources/messages/batches.test.ts, api.md

Cancellation is exposed as a batch operation in the API reference and should be modeled as best-effort cancellation before processing ends. Once cancellation is initiated, the batch can enter canceling; some non-interruptible work may complete anyway. That means cancellation handlers should not mark every outstanding item as canceled at the moment the cancel call returns. Instead, persist that cancellation was requested, continue tracking until the batch reaches a terminal state, and then reconcile the individual result stream. The exported canceled, expired, errored, and succeeded result types support this final reconciliation step.

Sources: src/resources/messages/index.ts, api.md

Result handling should be written as a variant dispatch. A succeeded item contains the generated Message response for its original request. An errored item represents a request-level failure that did not produce a Message. Canceled and expired items are also terminal and should usually be recorded distinctly, because they may drive different retry or user-facing behavior. Since official docs warn that results can be out of request order, never combine results with original inputs by array index. Use custom_id, handle every result kind, and make retries idempotent around your own job identifiers.

Sources: src/resources/messages/index.ts, api.md

Stable and Beta Differences

The beta batch surface exists for callers using beta capabilities inside Message requests. The beta generated test starts with the same required shape as stable create, then demonstrates additional fields: a structured container with skills, context_management edits, diagnostics, fallback credit tokens, fallback model definitions, MCP server configuration, output budgets, output formats, service speed, and other beta-oriented request controls. These fields connect batch processing to broader Claude platform features, such as MCP tool access and skills, but they should be gated by the documented beta headers and feature availability for your account.

Sources: tests/api-resources/beta/messages/batches.test.ts, api.md

Choose the namespace by the request contract you need. If the payload only uses stable Messages parameters, prefer client.messages.batches so your integration depends on the generally available SDK surface. If the payload includes beta-only fields, use client.beta.messages.batches and keep beta names, headers, and rollout assumptions close to the calling code. This separation makes migrations easier: stable batch infrastructure, persistence, polling, and result reconciliation can remain the same while the request-building layer decides whether a specific job requires beta behavior.

Sources: tests/api-resources/messages/batches.test.ts, tests/api-resources/beta/messages/batches.test.ts

Implementation and Testing Signals

The batch resources and tests are generated from the OpenAPI specification by Stainless, which is stated in the test and export file headers. That generation pattern matters for maintainers because changes to method availability, parameter names, or exported types usually flow from API specification updates rather than handwritten resource code. The tests provide contract signals rather than business-logic examples: they instantiate Anthropic, point it at a test base URL, call resource methods, and assert response wrapper semantics. When upgrading the SDK, these tests are useful indicators of public surface continuity.

Sources: tests/api-resources/messages/batches.test.ts, tests/api-resources/beta/messages/batches.test.ts, src/resources/messages/index.ts

For application testing, mirror the SDK's own concerns. Unit tests should verify that your batch builder emits unique custom_id values and valid embedded Messages params. Integration tests should cover create, retrieve/poll, cancellation if used, and result reconciliation for all terminal result variants. Operational tests should prove that raw response access is available where your logging or retry layer needs it. The SDK's .asResponse() and .withResponse() patterns are especially useful when you need typed data and HTTP-level evidence from the same call.

Sources: tests/api-resources/messages/batches.test.ts

Next Steps

After implementing create and polling, add a dedicated result consumer that narrows every MessageBatchResult variant and records outcomes by custom_id. Then decide whether your workload needs beta-only Message features such as MCP servers, skills, context management, or fallbacks; if it does, isolate those request builders behind client.beta.messages.batches while keeping common reconciliation code namespace-neutral. For adjacent details, read the Messages API reference for the embedded request shape, the Message Batches guide for workflow design, and request-options documentation for retries, raw responses, and error handling.