Skip to content
My Docs My Docs letta-sdk
  • Auto
  • Light
  • Dark
DiscordForumGitHubSign up
API Reference
Groups
Messages
View as Markdown
Copy Markdown
Open in Claude
Open in ChatGPT

List Group Messages

groups.messages.list(strgroup_id, MessageListParams**kwargs) -> SyncArrayPage[LettaMessageUnion]
get/v1/groups/{group_id}/messages

Retrieve message history for an agent.

ParametersExpand Collapse
group_id: str

The ID of the group in the format 'group-'

minLength42
maxLength42
after: Optional[str]

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

Deprecatedassistant_message_tool_kwarg: Optional[str]

The name of the message argument.

Deprecatedassistant_message_tool_name: Optional[str]

The name of the designated message tool.

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 retrieve

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"
Deprecateduse_assistant_message: Optional[bool]

Whether to use assistant messages

ReturnsExpand Collapse
LettaMessageUnion = LettaMessageUnion

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system

Accepts one of the following:
class SystemMessage: …

A message generated by the system. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (str): The message content sent by the system

id: str
content: str

The message content sent by the system

date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["system_message"]]

The type of the message.

Accepts one of the following:
"system_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class UserMessage: …

A message sent by the user. Never streamed back on a response, only used for cursor pagination.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaUserMessageContentUnion]]): The message content sent by the user (can be a string or an array of multi-modal content parts)

id: str
content: Union[List[LettaUserMessageContentUnion], str]

The message content sent by the user (can be a string or an array of multi-modal content parts)

Accepts one of the following:
ContentUnionMember0 = List[LettaUserMessageContentUnion]
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"
ContentUnionMember1 = str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["user_message"]]

The type of the message.

Accepts one of the following:
"user_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ReasoningMessage: …

Representation of an agent's internal reasoning.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message source (Literal["reasoner_model", "non_reasoner_model"]): Whether the reasoning content was generated natively by a reasoner model or derived via prompting reasoning (str): The internal reasoning of the agent signature (Optional[str]): The model-generated signature of the reasoning step

id: str
date: datetime
reasoning: str
is_err: Optional[bool]
message_type: Optional[Literal["reasoning_message"]]

The type of the message.

Accepts one of the following:
"reasoning_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
signature: Optional[str]
source: Optional[Literal["reasoner_model", "non_reasoner_model"]]
Accepts one of the following:
"reasoner_model"
"non_reasoner_model"
step_id: Optional[str]
class HiddenReasoningMessage: …

Representation of an agent's internal reasoning where reasoning content has been hidden from the response.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message state (Literal["redacted", "omitted"]): Whether the reasoning content was redacted by the provider or simply omitted by the API hidden_reasoning (Optional[str]): The internal reasoning of the agent

id: str
date: datetime
state: Literal["redacted", "omitted"]
Accepts one of the following:
"redacted"
"omitted"
hidden_reasoning: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["hidden_reasoning_message"]]

The type of the message.

Accepts one of the following:
"hidden_reasoning_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ToolCallMessage: …

A message representing a request to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (Union[ToolCall, ToolCallDelta]): The tool call

id: str
date: datetime
Deprecatedtool_call: ToolCall
Accepts one of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["tool_call_message"]]

The type of the message.

Accepts one of the following:
"tool_call_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]
Accepts one of the following:
ToolCallsUnionMember0 = List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ToolReturnMessage: …

A message representing the return value of a tool call (generated by Letta executing the requested tool).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_return (str): The return value of the tool (deprecated, use tool_returns) status (Literal["success", "error"]): The status of the tool call (deprecated, use tool_returns) tool_call_id (str): A unique identifier for the tool call that generated this message (deprecated, use tool_returns) stdout (Optional[List(str)]): Captured stdout (e.g. prints, logs) from the tool invocation (deprecated, use tool_returns) stderr (Optional[List(str)]): Captured stderr from the tool invocation (deprecated, use tool_returns) tool_returns (Optional[List[ToolReturn]]): List of tool returns for multi-tool support

id: str
date: datetime
Deprecatedstatus: Literal["success", "error"]
Accepts one of the following:
"success"
"error"
Deprecatedtool_call_id: str
Deprecatedtool_return: str
is_err: Optional[bool]
message_type: Optional[Literal["tool_return_message"]]

The type of the message.

Accepts one of the following:
"tool_return_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
Deprecatedstderr: Optional[List[str]]
Deprecatedstdout: Optional[List[str]]
step_id: Optional[str]
tool_returns: Optional[List[ToolReturn]]
status: Literal["success", "error"]
Accepts one of the following:
"success"
"error"
tool_call_id: str
tool_return: str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

Accepts one of the following:
"tool"
class AssistantMessage: …

A message sent by the LLM in response to user input. Used in the LLM context.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message content (Union[str, List[LettaAssistantMessageContentUnion]]): The message content sent by the agent (can be a string or an array of content parts)

id: str
content: Union[List[LettaAssistantMessageContentUnion], str]

The message content sent by the agent (can be a string or an array of content parts)

Accepts one of the following:
ContentUnionMember0 = List[LettaAssistantMessageContentUnion]
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"
ContentUnionMember1 = str
date: datetime
is_err: Optional[bool]
message_type: Optional[Literal["assistant_message"]]

The type of the message.

Accepts one of the following:
"assistant_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class ApprovalRequestMessage: …

A message representing a request for approval to call a tool (generated by the LLM to trigger tool execution).

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message tool_call (ToolCall): The tool call

id: str
date: datetime
Deprecatedtool_call: ToolCall

The tool call that has been requested by the llm to run

Accepts one of the following:
class ToolCall: …
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
is_err: Optional[bool]
message_type: Optional[Literal["approval_request_message"]]

The type of the message.

Accepts one of the following:
"approval_request_message"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
tool_calls: Optional[ToolCalls]

The tool calls that have been requested by the llm to run, which are pending approval

Accepts one of the following:
ToolCallsUnionMember0 = List[ToolCall]
arguments: str
name: str
tool_call_id: str
class ToolCallDelta: …
arguments: Optional[str]
name: Optional[str]
tool_call_id: Optional[str]
class ApprovalResponseMessage: …

A message representing a response form the user indicating whether a tool has been approved to run.

Args: id (str): The ID of the message date (datetime): The date the message was created in ISO format name (Optional[str]): The name of the sender of the message approve: (bool) Whether the tool has been approved approval_request_id: The ID of the approval request reason: (Optional[str]) An optional explanation for the provided approval status

id: str
date: datetime
Deprecatedapproval_request_id: Optional[str]

The message ID of the approval request

approvals: Optional[List[Approval]]

The list of approval responses

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 ToolReturn: …
status: Literal["success", "error"]
Accepts one of the following:
"success"
"error"
tool_call_id: str
tool_return: str
stderr: Optional[List[str]]
stdout: Optional[List[str]]
type: Optional[Literal["tool"]]

The message type to be created.

Accepts one of the following:
"tool"
Deprecatedapprove: Optional[bool]

Whether the tool has been approved

is_err: Optional[bool]
message_type: Optional[Literal["approval_response_message"]]

The type of the message.

Accepts one of the following:
"approval_response_message"
name: Optional[str]
otid: Optional[str]
Deprecatedreason: Optional[str]

An optional explanation for the provided approval status

run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class SummaryMessage: …

A message representing a summary of the conversation. Sent to the LLM as a user or system message depending on the provider.

id: str
date: datetime
summary: str
is_err: Optional[bool]
message_type: Optional[Literal["summary"]]
Accepts one of the following:
"summary"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
class EventMessage: …

A message for notifying the developer that an event that has occured (e.g. a compaction). Events are NOT part of the context window.

id: str
date: datetime
event_data: Dict[str, object]
event_type: Literal["compaction"]
Accepts one of the following:
"compaction"
is_err: Optional[bool]
message_type: Optional[Literal["event"]]
Accepts one of the following:
"event"
name: Optional[str]
otid: Optional[str]
run_id: Optional[str]
sender_id: Optional[str]
seq_id: Optional[int]
step_id: Optional[str]
List Group Messages
  • HTTP
  • TypeScript
  • Python
from letta_client import Letta

client = Letta(
    api_key="My API Key",
)
page = client.groups.messages.list(
    group_id="group-123e4567-e89b-42d3-8456-426614174000",
)
page = page.items[0]
print(page)
[
  {
    "id": "id",
    "content": "content",
    "date": "2019-12-27T18:11:19.117Z",
    "is_err": true,
    "message_type": "system_message",
    "name": "name",
    "otid": "otid",
    "run_id": "run_id",
    "sender_id": "sender_id",
    "seq_id": 0,
    "step_id": "step_id"
  }
]
Returns Examples
[
  {
    "id": "id",
    "content": "content",
    "date": "2019-12-27T18:11:19.117Z",
    "is_err": true,
    "message_type": "system_message",
    "name": "name",
    "otid": "otid",
    "run_id": "run_id",
    "sender_id": "sender_id",
    "seq_id": 0,
    "step_id": "step_id"
  }
]