--- title: "Search Messages" method: POST path: "/v1/agents/messages/search" tags: ["agents"] --- # Search Messages `POST /v1/agents/messages/search` Search messages across the entire organization with optional project and template filtering. Returns messages with FTS/vector ranks and total RRF score. This is a cloud-only feature. ## Request body - MessageSearchRequest — Request model for searching messages across the organization - `query` string, nullable — Text query for full-text search - `search_mode` 'vector' | 'fts' | 'hybrid' — Search mode to use - `roles` MessageRole[], nullable — Filter messages by role - `project_id` string, nullable — Filter messages by project ID - `template_id` string, nullable — Filter messages by template ID - `limit` integer — Maximum number of results to return - `start_date` string, date-time, nullable — Filter messages created after this date - `end_date` string, date-time, nullable — Filter messages created on or before this date ## Response `200` Successful Response - MessageSearchResult[] - `embedded_text` string, required — The embedded content (LLM-friendly) - `message` Message, required — 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. t - `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 timestamp when the object was created. - `updated_at` string, date-time, nullable — The timestamp when the object was last updated. - `id` string — The human-friendly ID of the Message - `agent_id` string, nullable — The unique identifier of the agent. - `model` string, nullable — The model used to make the function call. - `role` 'assistant' | 'user' | 'tool' | 'function' | 'system' | 'approval', required - `content` union[], nullable — The content of the message. - union - TextContent - `type` 'text' — The type of the message. - `text` string, required — The text content of the message. - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this text content. - ImageContent - `type` 'image' — The type of the message. - `source` union, required — The source of the image. - UrlImage - … - Base64Image - … - LettaImage - … - ToolCallContent - `type` 'tool_call' — Indicates this content represents a tool call event. - `id` string, required — A unique identifier for this specific tool call instance. - `name` string, required — The name of the tool being called. - `input` object, required — The parameters being passed to the tool, structured as a dictionary of parameter names to values. - `signature` string, nullable — Stores a unique identifier for any reasoning associated with this tool call. - ToolReturnContent - `type` 'tool_return' — Indicates this content represents a tool return event. - `tool_call_id` string, required — References the ID of the ToolCallContent that initiated this tool call. - `content` string, required — The content returned by the tool execution. - `is_error` boolean, required — Indicates whether the tool execution resulted in an error. - ReasoningContent — Sent via the Anthropic Messages API - `type` 'reasoning' — Indicates this is a reasoning/intermediate step. - `is_native` boolean, required — Whether the reasoning content was generated by a reasoner model that processed this step. - `reasoning` string, required — The intermediate reasoning or thought process content. - `signature` string, nullable — A unique identifier for this reasoning step. - RedactedReasoningContent — Sent via the Anthropic Messages API - `type` 'redacted_reasoning' — Indicates this is a redacted thinking step. - `data` string, required — The redacted or filtered intermediate reasoning content. - OmittedReasoningContent — A placeholder for reasoning content we know is present, but isn't returned by the provider (e.g. OpenAI GPT-5 on ChatCompletions) - `type` 'omitted_reasoning' — Indicates this is an omitted reasoning step. - `signature` string, nullable — A unique identifier for this reasoning step. - SummarizedReasoningContent — The style of reasoning content returned by the OpenAI Responses API - `type` 'summarized_reasoning' — Indicates this is a summarized reasoning step. - `id` string, required — The unique identifier for this reasoning step. - `summary` SummarizedReasoningContentPart[], required — Summaries of the reasoning content. - `index` integer, required — The index of the summary part. - `text` string, required — The text of the summary part. - `encrypted_content` string — The encrypted reasoning content. - `name` string, nullable — For role user/assistant: the (optional) name of the participant. For role tool/function: the name of the function called. - `tool_calls` ChatCompletionMessageFunctionToolCall[], nullable — The list of tool calls requested. Only applicable for role assistant. - `id` string, required - `function` Function, required - `arguments` string, required - `name` string, required - `type` 'function', required - `tool_call_id` string, nullable — The ID of the tool call. Only applicable for role tool. - `step_id` string, nullable — The id of the step that this message was created in. - `run_id` string, nullable — The id of the run that this message was created in. - `otid` string, nullable — The offline threading id associated with this message - `tool_returns` LettaSchemasMessageToolReturn[], nullable — Tool execution return information for prior tool calls - `tool_call_id` unknown - `status` 'success' | 'error', required — The status of the tool call - `stdout` string[], nullable — Captured stdout (e.g. prints, logs) from the tool invocation - `stderr` string[], nullable — Captured stderr from the tool invocation - `func_response` string, nullable — The function response string - `group_id` string, nullable — The multi-agent group that the message was sent in - `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 - `is_err` boolean, nullable — Whether this message is part of an error step. Used only for debugging purposes. - `approval_request_id` string, nullable — The id of the approval request if this message is associated with a tool call request. - `approve` boolean, nullable — Whether tool call is approved. - `denial_reason` string, nullable — The reason the tool call request was denied. - `fts_rank` integer, nullable — Full-text search rank position if FTS was used - `vector_rank` integer, nullable — Vector search rank position if vector search was used - `rrf_score` number, required — Reciprocal Rank Fusion combined score ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.net/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)