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

# Create Batch

`POST /v1/messages/batches`

Submit a batch of agent runs for asynchronous processing.

Creates a job that will fan out messages to all listed agents and process them in parallel.
The request will be rejected if it exceeds 256MB.

## Request body

- CreateBatch
  - `requests` LettaBatchRequest[], required — List of requests to be processed in batch.
    - `messages` union[], required — The messages to be sent to the agent.
      - union
        - MessageCreate — Request to create a message
          - `type` 'message', nullable — The message type to be created.
          - `role` 'user' | 'system' | 'assistant', required — The role of the participant.
          - `content` union, required — The content of the message.
            - LettaMessageContentUnion[]
              - …
            - string
          - `name` string, nullable — The name of the participant.
          - `otid` string, nullable — The offline threading id associated with this message
          - `sender_id` string, nullable — The id of the sender of the message, can be an identity id or agent id
          - `batch_item_id` string, nullable — The id of the LLMBatchItem that this message is associated with
          - `group_id` string, nullable — The multi-agent group that the message was sent in
        - ApprovalCreate — Input to approve or deny a tool call request
          - `type` 'approval' — The message type to be created.
          - `approve` boolean, required — Whether the tool has been approved
          - `approval_request_id` string, required — The message ID of the approval request
          - `reason` string, nullable — An optional explanation for the provided approval status
    - `max_steps` integer — Maximum number of steps the agent should take to process the request.
    - `use_assistant_message` boolean — Whether the server should parse specific tool call arguments (default `send_message`) as `AssistantMessage` objects.
    - `assistant_message_tool_name` string — The name of the designated message tool.
    - `assistant_message_tool_kwarg` string — The name of the message argument in the designated message tool.
    - `include_return_message_types` MessageType[], nullable — Only return specified message types in the response. If `None` (default) returns all messages.
    - `enable_thinking` string — If set to True, enables reasoning before responses or tool calls from the agent.
    - `agent_id` string, required — The ID of the agent to send this batch request for
  - `callback_url` string, uri, nullable — Optional URL to call via POST when the batch completes. The callback payload will be a JSON object with the following fields: {'job_id': string, 'status': string, 'completed_at': string}. Where 'job_id' is the unique batch job identifier, 'status' is the final batch status (e.g., 'completed', 'failed'), and 'completed_at' is an ISO 8601 timestamp indicating when the batch job completed.

## Response `200`

Successful Response

- BatchJob
  - `created_by_id` string, nullable — The id of the user that made this object.
  - `last_updated_by_id` string, nullable — The id of the user that made this object.
  - `created_at` string, date-time — The unix timestamp of when the job was created.
  - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
  - `status` 'created' | 'running' | 'completed' | 'failed' | 'pending' | 'cancelled' | 'expired' — Status of the job.
  - `completed_at` string, date-time, nullable — The unix timestamp of when the job was completed.
  - `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
  - `metadata` object, nullable — The metadata of the job.
  - `job_type` 'job' | 'run' | 'batch'
  - `background` boolean, nullable — Whether the job was created in background mode.
  - `agent_id` string, nullable — The agent associated with this job/run.
  - `callback_url` string, nullable — If set, POST to this URL when the job completes.
  - `callback_sent_at` string, date-time, nullable — Timestamp when the callback was last attempted.
  - `callback_status_code` integer, nullable — HTTP status code returned by the callback endpoint.
  - `callback_error` string, nullable — Optional error message from attempting to POST the callback endpoint.
  - `ttft_ns` integer, nullable — Time to first token for a run in nanoseconds
  - `total_duration_ns` integer, nullable — Total run duration in nanoseconds
  - `id` string — The human-friendly ID of the Job

## Other responses

- `422` — Validation Error

## Changes

- **2025-10-03** `f0554a0bf8b2` — 3 info
  - added the new optional request property `requests/items/messages/items/anyOf[subschema #1: MessageCreate]/content/anyOf[subschema #1]/items/oneOf[subschema #1: TextContent]/signature`
  - added the new optional request property `requests/items/messages/items/anyOf[subschema #1: MessageCreate]/content/anyOf[subschema #1]/items/oneOf[subschema #3: ToolCallContent]/signature`
  - added the new optional request property `requests/items/messages/items/anyOf[subschema #1: MessageCreate]/content/anyOf[subschema #1]/items/oneOf[subschema #7: OmittedReasoningContent]/signature`
- **2025-09-18** `3a2d48137c08` — 2 info
  - added the optional property `agent_id` to the response with the `200` status
  - added the optional property `background` to the response with the `200` status

[Change history](https://skmtc.dev/yu-code666/apis/letta-api/changes/v1/messages/batches/post.md)

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)