---
title: "Create a Message Batch."
method: POST
path: "/v1/messages/batches"
tags: ["Messages"]
---

# Create a Message Batch.

`POST /v1/messages/batches`

Send a batch of message creation requests.

## Request body

- CreateMessageBatchRequest — Request body for POST /v1/messages/batches.
  - `requests` MessageBatchRequestParams[], required — List of requests for prompt completion.
    - `custom_id` string, required — Developer-provided ID for matching results to requests. Must be unique within the batch.
    - `params` AnthropicCreateMessageRequest, required — Request body for POST /v1/messages.
      - `model` string, required — The model to use for generation.
      - `messages` AnthropicMessage[], required — The messages in the conversation.
        - `role` 'user' | 'assistant' | 'system', required
        - `content` union, required — Message content: a string for simple text, or a list of content blocks.
          - string
          - union[]
            - union
              - …
      - `max_tokens` integer, required — The maximum number of tokens to generate.
      - `system` union — System prompt. A string or list of text blocks.
        - string
        - AnthropicTextBlock[]
          - `type` 'text'
          - `text` string, required
          - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
            - `type` 'ephemeral'
      - `tools` union[] — Tools available to the model.
        - union
          - AnthropicCustomToolDef — Definition of a custom (function-calling) tool.
            - `type` 'custom'
            - `name` string, required
            - `description` string, nullable
            - `input_schema` object, required — JSON Schema for the tool's input.
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicWebSearchTool — Built-in web search tool (web_search_20250305).
            - `type` 'web_search_20250305'
            - `name` 'web_search'
            - `max_uses` integer, nullable
            - `allowed_domains` string[], nullable
            - `blocked_domains` string[], nullable
            - `user_location` WebSearchUserLocation
              - …
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicBashTool — Built-in bash tool (bash_20250124).
            - `type` 'bash_20250124'
            - `name` 'bash'
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
          - AnthropicTextEditorTool — Built-in text editor tool (all versions).
            - `type` 'text_editor_20250124' | 'text_editor_20250429' | 'text_editor_20250728', required
            - `name` string, required
            - `max_characters` integer, nullable
            - `cache_control` AnthropicCacheControl — Prompt-cache breakpoint marker.
              - …
      - `tool_choice` union — How the model should select tools. One of: 'auto', 'any', 'none', or {type: 'tool', name: '...'}.
        - ToolChoiceAuto
          - `type` 'auto'
          - `disable_parallel_tool_use` boolean, nullable
        - ToolChoiceAny
          - `type` 'any'
          - `disable_parallel_tool_use` boolean, nullable
        - ToolChoiceNone
          - `type` 'none'
        - ToolChoiceTool
          - `type` 'tool'
          - `name` string, required
          - `disable_parallel_tool_use` boolean, nullable
      - `stream` boolean — Whether to stream the response.
      - `temperature` number — Sampling temperature.
      - `top_p` number — Nucleus sampling parameter.
      - `top_k` integer — Top-k sampling parameter.
      - `stop_sequences` string[] — Custom stop sequences.
      - `metadata` object — Request metadata.
      - `thinking` AnthropicThinkingConfig — Configuration for extended thinking.
        - `type` 'enabled' | 'disabled' | 'adaptive'
        - `budget_tokens` integer, nullable — Maximum tokens for thinking.
      - `service_tier` string — Service tier to use.

## Response `200`

Successful Response

- MessageBatch — A Message Batch object.
  - `id` string, required — Unique object identifier (msgbatch_ prefix).
  - `type` 'message_batch'
  - `processing_status` 'in_progress' | 'canceling' | 'ended', required — Processing status of the Message Batch.
  - `request_counts` MessageBatchRequestCounts — Tallies of requests by their status within a batch.
    - `processing` integer — Number of requests currently processing.
    - `succeeded` integer — Number of successfully completed requests.
    - `errored` integer — Number of requests that encountered an error.
    - `canceled` integer — Number of canceled requests.
    - `expired` integer — Number of expired requests.
  - `created_at` string, required — RFC 3339 datetime when the batch was created.
  - `expires_at` string, required — RFC 3339 datetime when processing will expire.
  - `cancel_initiated_at` string, nullable — RFC 3339 datetime when cancellation was initiated.
  - `ended_at` string, nullable — RFC 3339 datetime when all processing ended.
  - `archived_at` string, nullable — RFC 3339 datetime when the batch was archived.
  - `results_url` string, nullable — URL to a .jsonl file containing the results.

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An error occurred

---

[API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/versions/f3f783962256/schema)