agents

Search Messages

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.

post/v1/agents/messages/search

Request body

querystring nullable

Text query for full-text search

search_mode'vector' | 'fts' | 'hybrid'

Search mode to use

rolesMessageRole[] nullable

Filter messages by role

project_idstring nullable

Filter messages by project ID

template_idstring nullable

Filter messages by template ID

limitinteger

Maximum number of results to return

start_datestring date-time nullable

Filter messages created after this date

end_datestring date-time nullable

Filter messages created on or before this date

Response

Successful Response

embedded_textstring required

The embedded content (LLM-friendly)

fts_rankinteger nullable

Full-text search rank position if FTS was used

vector_rankinteger nullable

Vector search rank position if vector search was used

rrf_scorenumber required

Reciprocal Rank Fusion combined score

Example response

[
  {
    "message": {
      "id": "message-123e4567-e89b-12d3-a456-426614174000"
    }
  }
]

Changes

Changed in 5 of the 36 revisions of this API.17

Oct 7, 202542a9cd544e131See the full diff
- ○
  added the optional property items/message/tool_returns/anyOf[subschema #1]/items/func_response to the response with the 200 status
  response-optional-property-added
Oct 7, 20251ba60b114a271See the full diff
- ○
  added the optional property items/message/tool_returns/anyOf[subschema #1]/items/tool_call_id to the response with the 200 status
  response-optional-property-added
Oct 3, 2025f0554a0bf8b23See the full diff
- ○
  added the optional property items/message/content/anyOf[subschema #1]/items/oneOf[subschema #1: TextContent]/signature to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/message/content/anyOf[subschema #1]/items/oneOf[subschema #3: ToolCallContent]/signature to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/message/content/anyOf[subschema #1]/items/oneOf[subschema #7: OmittedReasoningContent]/signature to the response with the 200 status
  response-optional-property-added
Sep 29, 2025ac8e1eb684041See the full diff
- ○
  added the optional property items/message/run_id to the response with the 200 status
  response-optional-property-added
Sep 24, 202568c3c741b87311See the full diff
- ▲
  added SummarizedReasoningContent to the items/message/content/anyOf[subschema #1]/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ○
  added summarized_reasoning discriminator mapping keys to the items/message/content/anyOf[subschema #1]/items/ response property for the response status 200
  response-property-discriminator-mapping-added

Full history