List Messages For Batch

batches.messages.list(, ) -> SyncObjectPage[Message]

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

Get response messages for a specific batch job.

ParametersExpand Collapse

batch_id: str

after: Optional[str]

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

agent_id: Optional[str]

Filter messages by agent ID

before: Optional[str]

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

limit: Optional[int]

Maximum number of messages to return

order: Optional[Literal["asc", "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[Literal["created_at"]]

Field to sort by

Accepts one of the following:

"created_at"

ReturnsExpand Collapse

class Message: …

Letta's internal representation of a message. Includes methods to convert to/from LLM provider formats.

Attributes:
    id (str): The unique identifier of the message.
    role (MessageRole): The role of the participant.
    text (str): The text of the message.
    user_id (str): The unique identifier of the user.
    agent_id (str): The unique identifier of the agent.
    model (str): The model used to make the function call.
    name (str): The name of the participant.
    created_at (datetime): The time the message was created.
    tool_calls (List[OpenAIToolCall,]): The list of tool calls requested.
    tool_call_id (str): The id of the tool call.
    step_id (str): The id of the step that this message was created in.
    otid (str): The offline threading id associated with this message.
    tool_returns (List[ToolReturn]): The list of tool returns requested.
    group_id (str): The multi-agent group that the message was sent in.
    sender_id (str): The id of the sender of the message, can be an identity id or agent id.

id: str

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[str]

The unique identifier of the agent.

approval_request_id: Optional[str]

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

approvals: Optional[List[Approval]]

The list of approvals for this message.

Accepts one of the following:

class ApprovalApprovalReturn: …

approve: bool

Whether the tool has been approved

tool_call_id: str

The ID of the tool call that corresponds to this approval

reason: Optional[str]

An optional explanation for the provided approval status

type: Optional[Literal["approval"]]

The message type to be created.

Accepts one of the following:

"approval"

class ApprovalLettaSchemasMessageToolReturn: …

status: Literal["success", "error"]

The status of the tool call

Accepts one of the following:

"success"

"error"

func_response: Optional[str]

The function response string

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

approve: Optional[bool]

Whether tool call is approved.

batch_item_id: Optional[str]

The id of the LLMBatchItem that this message is associated with

content: Optional[List[Content]]

The content of the message.

Accepts one of the following:

class TextContent: …

text: str

The text content of the message.

signature: Optional[str]

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

type: Optional[Literal["text"]]

The type of the message.

Accepts one of the following:

"text"

class ImageContent: …

source: Source

The source of the image.

Accepts one of the following:

class SourceURLImage: …

url: str

The URL of the image.

type: Optional[Literal["url"]]

The source type for the image.

Accepts one of the following:

"url"

class SourceBase64Image: …

data: str

The base64 encoded image data.

media_type: str

The media type for the image.

detail: Optional[str]

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

type: Optional[Literal["base64"]]

The source type for the image.

Accepts one of the following:

"base64"

class SourceLettaImage: …

file_id: str

The unique identifier of the image file persisted in storage.

data: Optional[str]

The base64 encoded image data.

detail: Optional[str]

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

media_type: Optional[str]

The media type for the image.

type: Optional[Literal["letta"]]

The source type for the image.

Accepts one of the following:

"letta"

type: Optional[Literal["image"]]

The type of the message.

Accepts one of the following:

"image"

class ToolCallContent: …

id: str

A unique identifier for this specific tool call instance.

input: Dict[str, object]

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[str]

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

type: Optional[Literal["tool_call"]]

Indicates this content represents a tool call event.

Accepts one of the following:

"tool_call"

class ToolReturnContent: …

content: str

The content returned by the tool execution.

is_error: bool

Indicates whether the tool execution resulted in an error.

tool_call_id: str

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

type: Optional[Literal["tool_return"]]

Indicates this content represents a tool return event.

Accepts one of the following:

"tool_return"

class ReasoningContent: …

Sent via the Anthropic Messages API

is_native: bool

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

reasoning: str

The intermediate reasoning or thought process content.

signature: Optional[str]

A unique identifier for this reasoning step.

type: Optional[Literal["reasoning"]]

Indicates this is a reasoning/intermediate step.

Accepts one of the following:

"reasoning"

class RedactedReasoningContent: …

Sent via the Anthropic Messages API

data: str

The redacted or filtered intermediate reasoning content.

type: Optional[Literal["redacted_reasoning"]]

Indicates this is a redacted thinking step.

Accepts one of the following:

"redacted_reasoning"

class OmittedReasoningContent: …

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[str]

A unique identifier for this reasoning step.

type: Optional[Literal["omitted_reasoning"]]

Indicates this is an omitted reasoning step.

Accepts one of the following:

"omitted_reasoning"

class ContentSummarizedReasoningContent: …

The style of reasoning content returned by the OpenAI Responses API

id: str

The unique identifier for this reasoning step.

summary: List[ContentSummarizedReasoningContentSummary]

Summaries of the reasoning content.

index: int

The index of the summary part.

text: str

The text of the summary part.

encrypted_content: Optional[str]

The encrypted reasoning content.

type: Optional[Literal["summarized_reasoning"]]

Indicates this is a summarized reasoning step.

Accepts one of the following:

"summarized_reasoning"

created_at: Optional[datetime]

The timestamp when the object was created.

formatdate-time

created_by_id: Optional[str]

The id of the user that made this object.

denial_reason: Optional[str]

The reason the tool call request was denied.

group_id: Optional[str]

The multi-agent group that the message was sent in

is_err: Optional[bool]

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

last_updated_by_id: Optional[str]

The id of the user that made this object.

model: Optional[str]

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[str]

The offline threading id associated with this message

run_id: Optional[str]

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

sender_id: Optional[str]

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

step_id: Optional[str]

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

tool_call_id: Optional[str]

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

tool_calls: Optional[List[ToolCall]]

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

id: str

function: ToolCallFunction

arguments: str

type: Literal["function"]

Accepts one of the following:

"function"

tool_returns: Optional[List[ToolReturn]]

Tool execution return information for prior tool calls

status: Literal["success", "error"]

The status of the tool call

Accepts one of the following:

"success"

"error"

func_response: Optional[str]

The function response string

stderr: Optional[List[str]]

Captured stderr from the tool invocation

stdout: Optional[List[str]]

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

tool_call_id: Optional[object]

The ID for the tool call

updated_at: Optional[datetime]

The timestamp when the object was last updated.

formatdate-time

List Messages For Batch

from letta_client import Letta

client = Letta(
    api_key="My API Key",
)
page = client.batches.messages.list(
    batch_id="batch_id",
)
page = page.messages[0]
print(page.id)

{
  "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"
    }
  ]
}