Search All Messages

post/v1/messages/search

Search messages across the organization with optional agent filtering. Returns messages with FTS/vector ranks and total RRF score.

This is a cloud-only feature.

Body ParametersExpand Collapse

query: string

Text query for full-text search

end_date: optional string

Filter messages created on or before this date

formatdate-time

limit: optional number

Maximum number of results to return

maximum100

minimum1

search_mode: optional "vector" or "fts" or "hybrid"

Search mode to use

Accepts one of the following:

"vector"

"fts"

"hybrid"

start_date: optional string

Filter messages created after this date

formatdate-time

ReturnsExpand Collapse

SystemMessage = object { content, created_at, message_id, 2 more }

System message list result with agent context.

Shape is identical to UpdateSystemMessage but includes the owning agent_id and message id.

content: string

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

created_at: string

The time the message was created in ISO format.

formatdate-time

message_id: string

The unique identifier of the message.

agent_id: optional string

The unique identifier of the agent that owns the message.

message_type: optional "system_message"

UserMessage = object { content, created_at, message_id, 2 more }

User message list result with agent context.

Shape is identical to UpdateUserMessage but includes the owning agent_id and message id.

content: array of LettaUserMessageContentUnion or string

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

Accepts one of the following:

UnionMember0 = array of LettaUserMessageContentUnion

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.

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.

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.

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.

type: optional "image"

The type of the message.

UnionMember1 = string

created_at: string

The time the message was created in ISO format.

formatdate-time

message_id: string

The unique identifier of the message.

agent_id: optional string

The unique identifier of the agent that owns the message.

message_type: optional "user_message"

ReasoningMessage = object { created_at, message_id, reasoning, 2 more }

Reasoning message list result with agent context.

Shape is identical to UpdateReasoningMessage but includes the owning agent_id and message id.

created_at: string

The time the message was created in ISO format.

formatdate-time

message_id: string

The unique identifier of the message.

reasoning: string

agent_id: optional string

The unique identifier of the agent that owns the message.

message_type: optional "reasoning_message"

AssistantMessage = object { content, created_at, message_id, 2 more }

Assistant message list result with agent context.

Shape is identical to UpdateAssistantMessage but includes the owning agent_id and message id.

content: array of LettaAssistantMessageContentUnion { text, signature, type } or string

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

Accepts one of the following:

UnionMember0 = array of LettaAssistantMessageContentUnion { 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.

UnionMember1 = string

created_at: string

The time the message was created in ISO format.

formatdate-time

message_id: string

The unique identifier of the message.

agent_id: optional string

The unique identifier of the agent that owns the message.

message_type: optional "assistant_message"

Search All Messages

curl https://api.letta.com/v1/messages/search \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LETTA_API_KEY" \
    -d '{
          "query": "query"
        }'

[
  {
    "content": "content",
    "created_at": "2019-12-27T18:11:19.117Z",
    "message_id": "message_id",
    "agent_id": "agent_id",
    "message_type": "system_message"
  }
]

Returns Examples

[
  {
    "content": "content",
    "created_at": "2019-12-27T18:11:19.117Z",
    "message_id": "message_id",
    "agent_id": "agent_id",
    "message_type": "system_message"
  }
]