Retrieve Message Batch Results

Streams the results of a Message Batch as a .jsonl file.

Each line in the file is a JSON object containing the result of a single request in the Message Batch. Results are not guaranteed to be in the same order as requests. Use the custom_id field to match results to requests.

Learn more about the Message Batches API in our user guide

GET /v1/messages/batches/{message_batch_id}/results

cURL

cURL

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d/results \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01"

200

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

The path for retrieving Message Batch results should be pulled from the batch’s results_url. This path should not be assumed and may change.

200

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}

Headers

anthropic-beta · string[]

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.

anthropic-version · string · required

The version of the Claude API you want to use.

Read more about versioning and our version history here.

x-api-key · string · required

Your unique API key for authentication.

This key is required in the header of all API requests, to authenticate your account and access Anthropic's services. Get your API key through the Console. Each key is scoped to a Workspace.

Path Parameters

message_batch_id · string · required

ID of the Message Batch.

Response

200

application/x-jsonl

Successful Response

This is a single line in the response .jsonl file and does not represent the response as a whole.

custom_id · string · required

Developer-provided ID created for each request in a Message Batch. Useful for matching results to requests, as results may be given out of request order.

Must be unique for each request within the Message Batch.

result · SucceededResult · object · required

Processing result for this request.

Contains a Message output if processing was successful, an error response if processing failed, or the reason why processing was not attempted, such as cancellation or expiration.

SucceededResult

Show child attributes

result. message · Message · object · required

Show child attributes

result.message. id · string · required

Unique object identifier.

The format and length of IDs may change over time.

result.message. type · string · default: message · required

Object type.

For Messages, this is always "message".

Allowed value: "message"

result.message. role · string · default: assistant · required

Conversational role of the generated message.

This will always be "assistant".

Allowed value: "assistant"

result.message. content · (Text · object | Thinking · object | Redacted thinking · object | Tool use · object | Server tool use · object | Web search tool result · object | ResponseWebFetchToolResultBlock · object | Code execution tool result · object | ResponseBashCodeExecutionToolResultBlock · object | ResponseTextEditorCodeExecutionToolResultBlock · object | MCP tool use · object | MCP tool result · object | Container upload · object)[] · required

Content generated by the model.

This is an array of content blocks, each of which has a type that determines its shape.

Example:

[{"type": "text", "text": "Hi, I'm Claude."}]

If the request input messages ended with an assistant turn, then the response content will continue directly from that last turn. You can use this to constrain the model's output.

For example, if the input messages were:

[
  {"role": "user", "content": "What's the Greek name for Sun? (A) Sol (B) Helios (C) Sun"},
  {"role": "assistant", "content": "The best answer is ("}
]

Then the response content might be:

[{"type": "text", "text": "B)"}]

Text

Show child attributes

result.message.content. citations · (Character location · object | Page location · object | Content block location · object | ResponseWebSearchResultLocationCitation · object | ResponseSearchResultLocationCitation · object)[] | null · required

Citations supporting the text block.

The type of citation returned will depend on the type of document being cited. Citing a PDF results in page_location, plain text results in char_location, and content document results in content_block_location.

Character location

Show child attributes

result.message.content.citations. cited_text · string · required

result.message.content.citations. document_index · integer · required

Required range: x >= 0

result.message.content.citations. document_title · string | null · required

result.message.content.citations. end_char_index · integer · required

result.message.content.citations. file_id · string | null · required

result.message.content.citations. start_char_index · integer · required

Required range: x >= 0

result.message.content.citations. type · string · default: char_location · required

Allowed value: "char_location"

result.message.content. text · string · required

Maximum string length: 5000000

result.message.content. type · string · default: text · required

Allowed value: "text"

result.message. model · string · required

The model that handled the request.

Required string length: 1 - 256

result.message. stop_reason · enum<string> | null · required

The reason that we stopped.

This may be one the following values:

• "end_turn": the model reached a natural stopping point
• "max_tokens": we exceeded the requested max_tokens or the model's maximum
• "stop_sequence": one of your provided custom stop_sequences was generated
• "tool_use": the model invoked one or more tools
• "pause_turn": we paused a long-running turn. You may provide the response back as-is in a subsequent request to let the model continue.
• "refusal": when streaming classifiers intervene to handle potential policy violations

In non-streaming mode this value is always non-null. In streaming mode, it is null in the message_start event and non-null otherwise.

Available options: end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal, model_context_window_exceeded

result.message. stop_sequence · string | null · required

Which custom stop sequence was generated, if any.

This value will be a non-null string if one of your custom stop sequences was generated.

result.message. usage · Usage · object · required

Billing and rate-limit usage.

Anthropic's API bills and rate-limits by token counts, as tokens represent the underlying cost to our systems.

Under the hood, the API transforms requests into a format suitable for the model. The model's output then goes through a parsing stage before becoming an API response. As a result, the token counts in usage will not match one-to-one with the exact visible content of an API request or response.

For example, output_tokens will be non-zero, even for an empty string response from Claude.

Total input tokens in a request is the summation of input_tokens, cache_creation_input_tokens, and cache_read_input_tokens.

Show child attributes

result.message.usage. cache_creation · CacheCreation · object · required

Breakdown of cached tokens by TTL

Show child attributes

result.message.usage.cache_creation. ephemeral_1h_input_tokens · integer · default: 0 · required

The number of input tokens used to create the 1 hour cache entry.

Required range: x >= 0

result.message.usage.cache_creation. ephemeral_5m_input_tokens · integer · default: 0 · required

The number of input tokens used to create the 5 minute cache entry.

Required range: x >= 0

result.message.usage. cache_creation_input_tokens · integer | null · required

The number of input tokens used to create the cache entry.

Required range: x >= 0

Example:

2051

result.message.usage. cache_read_input_tokens · integer | null · required

The number of input tokens read from the cache.

Required range: x >= 0

Example:

2051

result.message.usage. input_tokens · integer · required

The number of input tokens which were used.

Required range: x >= 0

result.message.usage. output_tokens · integer · required

The number of output tokens which were used.

Required range: x >= 0

result.message.usage. server_tool_use · ServerToolUsage · object · required

The number of server tool requests.

Show child attributes

result.message.usage.server_tool_use. web_fetch_requests · integer · default: 0 · required

The number of web fetch tool requests.

Required range: x >= 0

result.message.usage.server_tool_use. web_search_requests · integer · default: 0 · required

The number of web search tool requests.

Required range: x >= 0

result.message.usage. service_tier · enum<string> | null · required

If the request used the priority, standard, or batch tier.

Available options: standard, priority, batch

result.message. context_management · ResponseContextManagement · object · required

Context management response.

Information about context management strategies applied during the request.

Show child attributes

result.message.context_management. applied_edits · (ResponseClearToolUses20250919Edit · object | ResponseClearThinking20251015Edit · object)[] · required

List of context management edits that were applied.

ResponseClearToolUses20250919Edit

Show child attributes

result.message.context_management.applied_edits. cleared_input_tokens · integer · required

Number of input tokens cleared by this edit.

Required range: x >= 0

result.message.context_management.applied_edits. cleared_tool_uses · integer · required

Number of tool uses that were cleared.

Required range: x >= 0

result.message.context_management.applied_edits. type · string · default: clear_tool_uses_20250919 · required

The type of context management edit applied.

Allowed value: "clear_tool_uses_20250919"

result.message. container · Container · object · required

Information about the container used in this request.

This will be non-null if a container tool (e.g. code execution) was used.

Show child attributes

result.message.container. expires_at · string<date-time> · required

The time at which the container will expire.

result.message.container. id · string · required

Identifier for the container used in this request

result.message.container. skills · Skill · object[] | null · required

Skills loaded in the container

Show child attributes

result.message.container.skills. skill_id · string · required

Skill ID

Required string length: 1 - 64

result.message.container.skills. type · enum<string> · required

Type of skill - either 'anthropic' (built-in) or 'custom' (user-defined)

Available options: anthropic, custom

result.message.container.skills. version · string · required

Skill version or 'latest' for most recent version

Required string length: 1 - 64

result. type · string · default: succeeded · required

Allowed value: "succeeded"