## Retrieve Message Batch results

`messages.batches.results(message_batch_id) -> MessageBatchIndividualResponse`

**get** `/v1/messages/batches/{message_batch_id}/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](https://docs.claude.com/en/docs/build-with-claude/batch-processing)

### Parameters

- `message_batch_id: String`

  ID of the Message Batch.

### Returns

- `class MessageBatchIndividualResponse`

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

  - `custom_id: String`

    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: MessageBatchResult`

    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.

    - `class MessageBatchSucceededResult`

      - `message: Message`

        - `id: String`

          Unique object identifier.

          The format and length of IDs may change over time.

        - `container: Container`

          Information about the container used in the request (for the code execution tool)

          - `id: String`

            Identifier for the container used in this request

          - `expires_at: Time`

            The time at which the container will expire.

        - `content: Array[ContentBlock]`

          Content generated by the model.

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

          Example:

          ```json
          [{"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:

          ```json
          [
            {"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:

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

          - `class TextBlock`

            - `citations: Array[TextCitation]`

              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`.

              - `class CitationCharLocation`

                - `cited_text: String`

                - `document_index: Integer`

                - `document_title: String`

                - `end_char_index: Integer`

                - `file_id: String`

                - `start_char_index: Integer`

                - `type: :char_location`

                  - `:char_location`

              - `class CitationPageLocation`

                - `cited_text: String`

                - `document_index: Integer`

                - `document_title: String`

                - `end_page_number: Integer`

                - `file_id: String`

                - `start_page_number: Integer`

                - `type: :page_location`

                  - `:page_location`

              - `class CitationContentBlockLocation`

                - `cited_text: String`

                  The full text of the cited block range, concatenated.

                  Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.

                - `document_index: Integer`

                - `document_title: String`

                - `end_block_index: Integer`

                  Exclusive 0-based end index of the cited block range in the source's `content` array.

                  Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.

                - `file_id: String`

                - `start_block_index: Integer`

                  0-based index of the first cited block in the source's `content` array.

                - `type: :content_block_location`

                  - `:content_block_location`

              - `class CitationsWebSearchResultLocation`

                - `cited_text: String`

                - `encrypted_index: String`

                - `title: String`

                - `type: :web_search_result_location`

                  - `:web_search_result_location`

                - `url: String`

              - `class CitationsSearchResultLocation`

                - `cited_text: String`

                  The full text of the cited block range, concatenated.

                  Always equals the contents of `content[start_block_index:end_block_index]` joined together. The text block is the minimal citable unit; this field is never a substring of a single block. Not counted toward output tokens, and not counted toward input tokens when sent back in subsequent turns.

                - `end_block_index: Integer`

                  Exclusive 0-based end index of the cited block range in the source's `content` array.

                  Always greater than `start_block_index`; a single-block citation has `end_block_index = start_block_index + 1`.

                - `search_result_index: Integer`

                  0-based index of the cited search result among all `search_result` content blocks in the request, in the order they appear across messages and tool results.

                  Counted separately from `document_index`; server-side web search results are not included in this count.

                - `source: String`

                - `start_block_index: Integer`

                  0-based index of the first cited block in the source's `content` array.

                - `title: String`

                - `type: :search_result_location`

                  - `:search_result_location`

            - `text: String`

            - `type: :text`

              - `:text`

          - `class ThinkingBlock`

            - `signature: String`

            - `thinking: String`

            - `type: :thinking`

              - `:thinking`

          - `class RedactedThinkingBlock`

            - `data: String`

            - `type: :redacted_thinking`

              - `:redacted_thinking`

          - `class ToolUseBlock`

            - `id: String`

            - `caller_: DirectCaller | ServerToolCaller | ServerToolCaller20260120`

              Tool invocation directly from the model.

              - `class DirectCaller`

                Tool invocation directly from the model.

                - `type: :direct`

                  - `:direct`

              - `class ServerToolCaller`

                Tool invocation generated by a server-side tool.

                - `tool_id: String`

                - `type: :code_execution_20250825`

                  - `:code_execution_20250825`

              - `class ServerToolCaller20260120`

                - `tool_id: String`

                - `type: :code_execution_20260120`

                  - `:code_execution_20260120`

            - `input: Hash[Symbol, untyped]`

            - `name: String`

            - `type: :tool_use`

              - `:tool_use`

          - `class ServerToolUseBlock`

            - `id: String`

            - `caller_: DirectCaller | ServerToolCaller | ServerToolCaller20260120`

              Tool invocation directly from the model.

              - `class DirectCaller`

                Tool invocation directly from the model.

              - `class ServerToolCaller`

                Tool invocation generated by a server-side tool.

              - `class ServerToolCaller20260120`

            - `input: Hash[Symbol, untyped]`

            - `name: :web_search | :web_fetch | :code_execution | 4 more`

              - `:web_search`

              - `:web_fetch`

              - `:code_execution`

              - `:bash_code_execution`

              - `:text_editor_code_execution`

              - `:tool_search_tool_regex`

              - `:tool_search_tool_bm25`

            - `type: :server_tool_use`

              - `:server_tool_use`

          - `class WebSearchToolResultBlock`

            - `caller_: DirectCaller | ServerToolCaller | ServerToolCaller20260120`

              Tool invocation directly from the model.

              - `class DirectCaller`

                Tool invocation directly from the model.

              - `class ServerToolCaller`

                Tool invocation generated by a server-side tool.

              - `class ServerToolCaller20260120`

            - `content: WebSearchToolResultBlockContent`

              - `class WebSearchToolResultError`

                - `error_code: WebSearchToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:unavailable`

                  - `:max_uses_exceeded`

                  - `:too_many_requests`

                  - `:query_too_long`

                  - `:request_too_large`

                - `type: :web_search_tool_result_error`

                  - `:web_search_tool_result_error`

              - `UnionMember1 = Array[WebSearchResultBlock]`

                - `encrypted_content: String`

                - `page_age: String`

                - `title: String`

                - `type: :web_search_result`

                  - `:web_search_result`

                - `url: String`

            - `tool_use_id: String`

            - `type: :web_search_tool_result`

              - `:web_search_tool_result`

          - `class WebFetchToolResultBlock`

            - `caller_: DirectCaller | ServerToolCaller | ServerToolCaller20260120`

              Tool invocation directly from the model.

              - `class DirectCaller`

                Tool invocation directly from the model.

              - `class ServerToolCaller`

                Tool invocation generated by a server-side tool.

              - `class ServerToolCaller20260120`

            - `content: WebFetchToolResultErrorBlock | WebFetchBlock`

              - `class WebFetchToolResultErrorBlock`

                - `error_code: WebFetchToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:url_too_long`

                  - `:url_not_allowed`

                  - `:url_not_in_prior_context`

                  - `:url_not_accessible`

                  - `:unsupported_content_type`

                  - `:too_many_requests`

                  - `:max_uses_exceeded`

                  - `:unavailable`

                - `type: :web_fetch_tool_result_error`

                  - `:web_fetch_tool_result_error`

              - `class WebFetchBlock`

                - `content: DocumentBlock`

                  - `citations: CitationsConfig`

                    Citation configuration for the document

                    - `enabled: bool`

                  - `source: Base64PDFSource | PlainTextSource`

                    - `class Base64PDFSource`

                      - `data: String`

                      - `media_type: :"application/pdf"`

                        - `:"application/pdf"`

                      - `type: :base64`

                        - `:base64`

                    - `class PlainTextSource`

                      - `data: String`

                      - `media_type: :"text/plain"`

                        - `:"text/plain"`

                      - `type: :text`

                        - `:text`

                  - `title: String`

                    The title of the document

                  - `type: :document`

                    - `:document`

                - `retrieved_at: String`

                  ISO 8601 timestamp when the content was retrieved

                - `type: :web_fetch_result`

                  - `:web_fetch_result`

                - `url: String`

                  Fetched content URL

            - `tool_use_id: String`

            - `type: :web_fetch_tool_result`

              - `:web_fetch_tool_result`

          - `class CodeExecutionToolResultBlock`

            - `content: CodeExecutionToolResultBlockContent`

              Code execution result with encrypted stdout for PFC + web_search results.

              - `class CodeExecutionToolResultError`

                - `error_code: CodeExecutionToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:unavailable`

                  - `:too_many_requests`

                  - `:execution_time_exceeded`

                - `type: :code_execution_tool_result_error`

                  - `:code_execution_tool_result_error`

              - `class CodeExecutionResultBlock`

                - `content: Array[CodeExecutionOutputBlock]`

                  - `file_id: String`

                  - `type: :code_execution_output`

                    - `:code_execution_output`

                - `return_code: Integer`

                - `stderr: String`

                - `stdout: String`

                - `type: :code_execution_result`

                  - `:code_execution_result`

              - `class EncryptedCodeExecutionResultBlock`

                Code execution result with encrypted stdout for PFC + web_search results.

                - `content: Array[CodeExecutionOutputBlock]`

                  - `file_id: String`

                  - `type: :code_execution_output`

                - `encrypted_stdout: String`

                - `return_code: Integer`

                - `stderr: String`

                - `type: :encrypted_code_execution_result`

                  - `:encrypted_code_execution_result`

            - `tool_use_id: String`

            - `type: :code_execution_tool_result`

              - `:code_execution_tool_result`

          - `class BashCodeExecutionToolResultBlock`

            - `content: BashCodeExecutionToolResultError | BashCodeExecutionResultBlock`

              - `class BashCodeExecutionToolResultError`

                - `error_code: BashCodeExecutionToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:unavailable`

                  - `:too_many_requests`

                  - `:execution_time_exceeded`

                  - `:output_file_too_large`

                - `type: :bash_code_execution_tool_result_error`

                  - `:bash_code_execution_tool_result_error`

              - `class BashCodeExecutionResultBlock`

                - `content: Array[BashCodeExecutionOutputBlock]`

                  - `file_id: String`

                  - `type: :bash_code_execution_output`

                    - `:bash_code_execution_output`

                - `return_code: Integer`

                - `stderr: String`

                - `stdout: String`

                - `type: :bash_code_execution_result`

                  - `:bash_code_execution_result`

            - `tool_use_id: String`

            - `type: :bash_code_execution_tool_result`

              - `:bash_code_execution_tool_result`

          - `class TextEditorCodeExecutionToolResultBlock`

            - `content: TextEditorCodeExecutionToolResultError | TextEditorCodeExecutionViewResultBlock | TextEditorCodeExecutionCreateResultBlock | TextEditorCodeExecutionStrReplaceResultBlock`

              - `class TextEditorCodeExecutionToolResultError`

                - `error_code: TextEditorCodeExecutionToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:unavailable`

                  - `:too_many_requests`

                  - `:execution_time_exceeded`

                  - `:file_not_found`

                - `error_message: String`

                - `type: :text_editor_code_execution_tool_result_error`

                  - `:text_editor_code_execution_tool_result_error`

              - `class TextEditorCodeExecutionViewResultBlock`

                - `content: String`

                - `file_type: :text | :image | :pdf`

                  - `:text`

                  - `:image`

                  - `:pdf`

                - `num_lines: Integer`

                - `start_line: Integer`

                - `total_lines: Integer`

                - `type: :text_editor_code_execution_view_result`

                  - `:text_editor_code_execution_view_result`

              - `class TextEditorCodeExecutionCreateResultBlock`

                - `is_file_update: bool`

                - `type: :text_editor_code_execution_create_result`

                  - `:text_editor_code_execution_create_result`

              - `class TextEditorCodeExecutionStrReplaceResultBlock`

                - `lines: Array[String]`

                - `new_lines: Integer`

                - `new_start: Integer`

                - `old_lines: Integer`

                - `old_start: Integer`

                - `type: :text_editor_code_execution_str_replace_result`

                  - `:text_editor_code_execution_str_replace_result`

            - `tool_use_id: String`

            - `type: :text_editor_code_execution_tool_result`

              - `:text_editor_code_execution_tool_result`

          - `class ToolSearchToolResultBlock`

            - `content: ToolSearchToolResultError | ToolSearchToolSearchResultBlock`

              - `class ToolSearchToolResultError`

                - `error_code: ToolSearchToolResultErrorCode`

                  - `:invalid_tool_input`

                  - `:unavailable`

                  - `:too_many_requests`

                  - `:execution_time_exceeded`

                - `error_message: String`

                - `type: :tool_search_tool_result_error`

                  - `:tool_search_tool_result_error`

              - `class ToolSearchToolSearchResultBlock`

                - `tool_references: Array[ToolReferenceBlock]`

                  - `tool_name: String`

                  - `type: :tool_reference`

                    - `:tool_reference`

                - `type: :tool_search_tool_search_result`

                  - `:tool_search_tool_search_result`

            - `tool_use_id: String`

            - `type: :tool_search_tool_result`

              - `:tool_search_tool_result`

          - `class ContainerUploadBlock`

            Response model for a file uploaded to the container.

            - `file_id: String`

            - `type: :container_upload`

              - `:container_upload`

        - `model: Model`

          The model that will complete your prompt.

          See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

          - `Model = :"claude-fable-5" | :"claude-mythos-5" | :"claude-opus-4-8" | 17 more`

            The model that will complete your prompt.

            See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.

            - `:"claude-fable-5"`

              Next generation of intelligence for the hardest knowledge work and coding problems

            - `:"claude-mythos-5"`

              Most capable model for cybersecurity and biology research

            - `:"claude-opus-4-8"`

              Frontier intelligence for long-running agents and coding

            - `:"claude-opus-4-7"`

              Frontier intelligence for long-running agents and coding

            - `:"claude-mythos-preview"`

              New class of intelligence, strongest in coding and cybersecurity

            - `:"claude-opus-4-6"`

              Frontier intelligence for long-running agents and coding

            - `:"claude-sonnet-4-6"`

              Best combination of speed and intelligence

            - `:"claude-haiku-4-5"`

              Fastest model with near-frontier intelligence

            - `:"claude-haiku-4-5-20251001"`

              Fastest model with near-frontier intelligence

            - `:"claude-opus-4-5"`

              Premium model combining maximum intelligence with practical performance

            - `:"claude-opus-4-5-20251101"`

              Premium model combining maximum intelligence with practical performance

            - `:"claude-sonnet-4-5"`

              High-performance model for agents and coding

            - `:"claude-sonnet-4-5-20250929"`

              High-performance model for agents and coding

            - `:"claude-opus-4-1"`

              Exceptional model for specialized complex tasks

            - `:"claude-opus-4-1-20250805"`

              Exceptional model for specialized complex tasks

            - `:"claude-opus-4-0"`

              Powerful model for complex tasks

            - `:"claude-opus-4-20250514"`

              Powerful model for complex tasks

            - `:"claude-sonnet-4-0"`

              High-performance model with extended thinking

            - `:"claude-sonnet-4-20250514"`

              High-performance model with extended thinking

            - `:"claude-3-haiku-20240307"`

              Fast and cost-effective model

          - `String = String`

        - `role: :assistant`

          Conversational role of the generated message.

          This will always be `"assistant"`.

          - `:assistant`

        - `stop_details: RefusalStopDetails`

          Structured information about a refusal.

          - `category: :cyber | :bio | :reasoning_extraction`

            The policy category that triggered the refusal.

            `null` when the refusal doesn't map to a named category.

            - `:cyber`

            - `:bio`

            - `:reasoning_extraction`

          - `explanation: String`

            Human-readable explanation of the refusal.

            This text is not guaranteed to be stable. `null` when no explanation is available for the category.

          - `type: :refusal`

            - `:refusal`

        - `stop_reason: StopReason`

          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.

          - `:end_turn`

          - `:max_tokens`

          - `:stop_sequence`

          - `:tool_use`

          - `:pause_turn`

          - `:refusal`

        - `stop_sequence: String`

          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.

        - `type: :message`

          Object type.

          For Messages, this is always `"message"`.

          - `:message`

        - `usage: Usage`

          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`.

          - `cache_creation: CacheCreation`

            Breakdown of cached tokens by TTL

            - `ephemeral_1h_input_tokens: Integer`

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

            - `ephemeral_5m_input_tokens: Integer`

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

          - `cache_creation_input_tokens: Integer`

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

          - `cache_read_input_tokens: Integer`

            The number of input tokens read from the cache.

          - `inference_geo: String`

            The geographic region where inference was performed for this request.

          - `input_tokens: Integer`

            The number of input tokens which were used.

          - `output_tokens: Integer`

            The number of output tokens which were used.

          - `output_tokens_details: OutputTokensDetails`

            Breakdown of output tokens by category.

            `output_tokens` remains the inclusive, authoritative total used for billing.
            This object provides a read-only decomposition for observability — for example,
            how many of the billed output tokens were spent on internal reasoning that may
            have been summarized before being returned to you.

            - `thinking_tokens: Integer`

              Number of output tokens the model generated as internal reasoning, including
              the thinking-block delimiter tokens.

              Reflects the raw reasoning the model produced, not the (possibly shorter)
              summarized thinking text returned in the response body. Computed by
              re-tokenizing the raw reasoning text, so it may differ from the model's exact
              generation count by a small number of tokens. Always ≤ `output_tokens`;
              `output_tokens - thinking_tokens` approximates the non-reasoning output.

          - `server_tool_use: ServerToolUsage`

            The number of server tool requests.

            - `web_fetch_requests: Integer`

              The number of web fetch tool requests.

            - `web_search_requests: Integer`

              The number of web search tool requests.

          - `service_tier: :standard | :priority | :batch`

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

            - `:standard`

            - `:priority`

            - `:batch`

      - `type: :succeeded`

        - `:succeeded`

    - `class MessageBatchErroredResult`

      - `error: ErrorResponse`

        - `error: ErrorObject`

          - `class InvalidRequestError`

            - `message: String`

            - `type: :invalid_request_error`

              - `:invalid_request_error`

          - `class AuthenticationError`

            - `message: String`

            - `type: :authentication_error`

              - `:authentication_error`

          - `class BillingError`

            - `message: String`

            - `type: :billing_error`

              - `:billing_error`

          - `class PermissionError`

            - `message: String`

            - `type: :permission_error`

              - `:permission_error`

          - `class NotFoundError`

            - `message: String`

            - `type: :not_found_error`

              - `:not_found_error`

          - `class RateLimitError`

            - `message: String`

            - `type: :rate_limit_error`

              - `:rate_limit_error`

          - `class GatewayTimeoutError`

            - `message: String`

            - `type: :timeout_error`

              - `:timeout_error`

          - `class APIErrorObject`

            - `message: String`

            - `type: :api_error`

              - `:api_error`

          - `class OverloadedError`

            - `message: String`

            - `type: :overloaded_error`

              - `:overloaded_error`

        - `request_id: String`

        - `type: :error`

          - `:error`

      - `type: :errored`

        - `:errored`

    - `class MessageBatchCanceledResult`

      - `type: :canceled`

        - `:canceled`

    - `class MessageBatchExpiredResult`

      - `type: :expired`

        - `:expired`

### Example

```ruby
require "anthropic"

anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")

message_batch_individual_response = anthropic.messages.batches.results("message_batch_id")

puts(message_batch_individual_response)
```