Search Messages
const url = 'https://example.com/api/v1/org/example/ws/example/sessions/example/messages/search?q=example&limit=50&include_compacted=false';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://example.com/api/v1/org/example/ws/example/sessions/example/messages/search?q=example&limit=50&include_compacted=false' \ --header 'Authorization: Bearer <token>'Full-text search over a session’s message content (ENG-7010). Backed by a tsvector @@ websearch_to_tsquery match with an ILIKE fallback for short queries the English parser strips away. Matches are returned in transcript order (seq ascending) and paged via after_seq; total reports the full match count. Accepts a full UUID or a unique prefix for session_id.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”Organization slug
Organization slug
Workspace slug
Workspace slug
Query Parameters
Section titled “Query Parameters ”Search query
Search query
Max matches per page
Max matches per page
Include compacted messages in the search
Include compacted messages in the search
Responses
Section titled “ Responses ”Successful Response
Result envelope for GET /sessions/{id}/messages/search.
object
True when more hits exist past this page; fetch with after_seq.
Single match from the session-message content search (ENG-7010).
A trimmed projection of :class:MessageResponse carrying only what
the transcript UI needs to render and navigate to a hit: identity
(id), ordering (seq), provenance (role, agent), the
content (truncated server-side so a large tool result doesn’t bloat
the response), and the original timestamp.
object
True when content was cut to the preview cap; the full message is available via the transcript endpoint at this seq.
Total matching messages in the session, across all pages — drives the ‘K of N’ affordance. matches is one page bounded by limit.
Example generated
{ "has_more": true, "matches": [ { "agent": "example", "content": "example", "content_truncated": true, "created_at": "2026-04-15T12:00:00Z", "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "role": "example", "seq": 1 } ], "total": 1}Invalid request
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Authentication failed
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Access forbidden
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Not found
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Already exists
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Validation error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Upgrade required
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Rate limited
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Internal server error
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Bad gateway
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}Gateway timeout
Canonical API error envelope returned by the API.
object
HTTP status code
Human-readable error message
object
Where the validation error occurred
Human-readable validation message
Machine-readable validation error type
Stable machine-readable error type
Example
{ "code": 401, "detail": "Authentication failed", "type": "authentication_error"}