List Messages For Batch

get/v1/messages/batches/{batch_id}/messages

Get response messages for a specific batch job.

Path ParametersExpand Collapse

batch_id: string

Query ParametersExpand Collapse

after: optional string

Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order

agent_id: optional string

Filter messages by agent ID

before: optional string

Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order

limit: optional number

Maximum number of messages to return

order: optional "asc" or "desc"

Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first

Accepts one of the following:

"asc"

"desc"

order_by: optional "created_at"

Field to sort by

Accepts one of the following:

"created_at"

ReturnsExpand Collapse

messages: array of Message { id, role, agent_id, 21 more }

id: string

The human-friendly ID of the Message

role: MessageRole

The role of the participant.

Accepts one of the following:

"assistant"

"user"

"tool"

"function"

"system"

"approval"

agent_id: optional string

The unique identifier of the agent.

approval_request_id: optional string

The id of the approval request if this message is associated with a tool call request.

approvals: optional array of object { approve, tool_call_id, reason, type } or object { status, func_response, stderr, 2 more }

The list of approvals for this message.

Accepts one of the following:

ApprovalReturn = object { approve, tool_call_id, reason, type }

approve: boolean

Whether the tool has been approved

tool_call_id: string

The ID of the tool call that corresponds to this approval

reason: optional string

An optional explanation for the provided approval status

type: optional "approval"

The message type to be created.

Accepts one of the following:

"approval"

LettaSchemasMessageToolReturn = object { status, func_response, stderr, 2 more }

status: "success" or "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func_response: optional string

The function response string

stderr: optional array of string

Captured stderr from the tool invocation

stdout: optional array of string

Captured stdout (e.g. prints, logs) from the tool invocation

tool_call_id: optional unknown

The ID for the tool call

approve: optional boolean

Whether tool call is approved.

batch_item_id: optional string

The id of the LLMBatchItem that this message is associated with

content: optional array of TextContent { text, signature, type } or ImageContent { source, type } or ToolCallContent { id, input, name, 2 more } or 5 more

The content of the message.

Accepts one of the following:

TextContent = object { text, signature, type }

text: string

The text content of the message.

signature: optional string

Stores a unique identifier for any reasoning associated with this text content.

type: optional "text"

The type of the message.

Accepts one of the following:

"text"

ImageContent = object { source, type }

source: object { url, type } or object { data, media_type, detail, type } or object { file_id, data, detail, 2 more }

The source of the image.

Accepts one of the following:

URL = object { url, type }

url: string

The URL of the image.

type: optional "url"

The source type for the image.

Accepts one of the following:

"url"

Base64 = object { data, media_type, detail, type }

data: string

The base64 encoded image data.

media_type: string

The media type for the image.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

type: optional "base64"

The source type for the image.

Accepts one of the following:

"base64"

Letta = object { file_id, data, detail, 2 more }

file_id: string

The unique identifier of the image file persisted in storage.

data: optional string

The base64 encoded image data.

detail: optional string

What level of detail to use when processing and understanding the image (low, high, or auto to let the model decide)

media_type: optional string

The media type for the image.

type: optional "letta"

The source type for the image.

Accepts one of the following:

"letta"

type: optional "image"

The type of the message.

Accepts one of the following:

"image"

ToolCallContent = object { id, input, name, 2 more }

id: string

A unique identifier for this specific tool call instance.

input: map[unknown]

The parameters being passed to the tool, structured as a dictionary of parameter names to values.

The name of the tool being called.

signature: optional string

Stores a unique identifier for any reasoning associated with this tool call.

type: optional "tool_call"

Indicates this content represents a tool call event.

Accepts one of the following:

"tool_call"

ToolReturnContent = object { content, is_error, tool_call_id, type }

content: string

The content returned by the tool execution.

is_error: boolean

Indicates whether the tool execution resulted in an error.

tool_call_id: string

References the ID of the ToolCallContent that initiated this tool call.

type: optional "tool_return"

Indicates this content represents a tool return event.

Accepts one of the following:

"tool_return"

ReasoningContent = object { is_native, reasoning, signature, type }

Sent via the Anthropic Messages API

is_native: boolean

Whether the reasoning content was generated by a reasoner model that processed this step.

reasoning: string

The intermediate reasoning or thought process content.

signature: optional string

A unique identifier for this reasoning step.

type: optional "reasoning"

Indicates this is a reasoning/intermediate step.

Accepts one of the following:

"reasoning"

RedactedReasoningContent = object { data, type }

Sent via the Anthropic Messages API

data: string

The redacted or filtered intermediate reasoning content.

type: optional "redacted_reasoning"

Indicates this is a redacted thinking step.

Accepts one of the following:

"redacted_reasoning"

OmittedReasoningContent = object { signature, type }

A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions)

signature: optional string

A unique identifier for this reasoning step.

type: optional "omitted_reasoning"

Indicates this is an omitted reasoning step.

Accepts one of the following:

"omitted_reasoning"

SummarizedReasoning = object { id, summary, encrypted_content, type }

The style of reasoning content returned by the OpenAI Responses API

id: string

The unique identifier for this reasoning step.

summary: array of object { index, text }

Summaries of the reasoning content.

index: number

The index of the summary part.

text: string

The text of the summary part.

encrypted_content: optional string

The encrypted reasoning content.

type: optional "summarized_reasoning"

Indicates this is a summarized reasoning step.

Accepts one of the following:

"summarized_reasoning"

created_at: optional string

The timestamp when the object was created.

formatdate-time

created_by_id: optional string

The id of the user that made this object.

denial_reason: optional string

The reason the tool call request was denied.

group_id: optional string

The multi-agent group that the message was sent in

is_err: optional boolean

Whether this message is part of an error step. Used only for debugging purposes.

last_updated_by_id: optional string

The id of the user that made this object.

model: optional string

The model used to make the function call.

For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called.

otid: optional string

The offline threading id associated with this message

run_id: optional string

The id of the run that this message was created in.

sender_id: optional string

The id of the sender of the message, can be an identity id or agent id

step_id: optional string

The id of the step that this message was created in.

tool_call_id: optional string

The ID of the tool call. Only applicable for role tool.

tool_calls: optional array of object { id, function, type }

The list of tool calls requested. Only applicable for role assistant.

id: string

function: object { arguments, name }

arguments: string

type: "function"

Accepts one of the following:

"function"

tool_returns: optional array of object { status, func_response, stderr, 2 more }

Tool execution return information for prior tool calls

status: "success" or "error"

The status of the tool call

Accepts one of the following:

"success"

"error"

func_response: optional string

The function response string

stderr: optional array of string

Captured stderr from the tool invocation

stdout: optional array of string

Captured stdout (e.g. prints, logs) from the tool invocation

tool_call_id: optional unknown

The ID for the tool call

updated_at: optional string

The timestamp when the object was last updated.

formatdate-time

List Messages For Batch

curl https://api.letta.com/v1/messages/batches/$BATCH_ID/messages \
    -H "Authorization: Bearer $LETTA_API_KEY"

{
  "messages": [
    {
      "id": "message-123e4567-e89b-12d3-a456-426614174000",
      "role": "assistant",
      "agent_id": "agent_id",
      "approval_request_id": "approval_request_id",
      "approvals": [
        {
          "approve": true,
          "tool_call_id": "tool_call_id",
          "reason": "reason",
          "type": "approval"
        }
      ],
      "approve": true,
      "batch_item_id": "batch_item_id",
      "content": [
        {
          "text": "text",
          "signature": "signature",
          "type": "text"
        }
      ],
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by_id": "created_by_id",
      "denial_reason": "denial_reason",
      "group_id": "group_id",
      "is_err": true,
      "last_updated_by_id": "last_updated_by_id",
      "model": "model",
      "name": "name",
      "otid": "otid",
      "run_id": "run_id",
      "sender_id": "sender_id",
      "step_id": "step_id",
      "tool_call_id": "tool_call_id",
      "tool_calls": [
        {
          "id": "id",
          "function": {
            "arguments": "arguments",
            "name": "name"
          },
          "type": "function"
        }
      ],
      "tool_returns": [
        {
          "status": "success",
          "func_response": "func_response",
          "stderr": [
            "string"
          ],
          "stdout": [
            "string"
          ],
          "tool_call_id": {}
        }
      ],
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ]
}

Returns Examples

{
  "messages": [
    {
      "id": "message-123e4567-e89b-12d3-a456-426614174000",
      "role": "assistant",
      "agent_id": "agent_id",
      "approval_request_id": "approval_request_id",
      "approvals": [
        {
          "approve": true,
          "tool_call_id": "tool_call_id",
          "reason": "reason",
          "type": "approval"
        }
      ],
      "approve": true,
      "batch_item_id": "batch_item_id",
      "content": [
        {
          "text": "text",
          "signature": "signature",
          "type": "text"
        }
      ],
      "created_at": "2019-12-27T18:11:19.117Z",
      "created_by_id": "created_by_id",
      "denial_reason": "denial_reason",
      "group_id": "group_id",
      "is_err": true,
      "last_updated_by_id": "last_updated_by_id",
      "model": "model",
      "name": "name",
      "otid": "otid",
      "run_id": "run_id",
      "sender_id": "sender_id",
      "step_id": "step_id",
      "tool_call_id": "tool_call_id",
      "tool_calls": [
        {
          "id": "id",
          "function": {
            "arguments": "arguments",
            "name": "name"
          },
          "type": "function"
        }
      ],
      "tool_returns": [
        {
          "status": "success",
          "func_response": "func_response",
          "stderr": [
            "string"
          ],
          "stdout": [
            "string"
          ],
          "tool_call_id": {}
        }
      ],
      "updated_at": "2019-12-27T18:11:19.117Z"
    }
  ]
}