Skip to main content
GET /search searches individual messages across all your traces and returns snippet-level hits. Every result carries a conversation_id (the trace ID) + message_index anchor, so you can jump straight to the surrounding turns with GET /conversations/:id/context.

Query parameters

string
required
The search query, 1–500 characters. Leading and trailing whitespace is trimmed; a whitespace-only query returns 400.
string
default:"hybrid"
keyword, semantic, or hybrid. Keyword matches literal substrings; semantic matches by meaning; hybrid fuses both. See Search modes.
string
Restrict results to traces from one end user. Maximum 200 characters.
string
default:"all"
One of all, 1h, 24h, 3d, 7d, 30d, 90d. Filters on each message’s timestamp. Imported history that stores placeholder timestamps before 2022 is filtered on the time Moda received the message instead.
string
Absolute start, inclusive: an ISO 8601 date (2026-10-07) or datetime (2026-10-07T14:00:00Z). UTC unless the value carries an offset. Uses the same message time as time_range, and the two combine as an intersection. Use it to single out one day or hour among many similar traces.
string
Absolute end, inclusive. A date-only value covers that whole UTC day, so since=2026-10-07&until=2026-10-07 is one day; a datetime includes that second. since must not be after until, and the range may span at most 366 days; otherwise the request fails with 400. With since or until set, prior_window_matched_conversations is null (an absolute range has no prior window).
integer
default:"20"
Maximum results to return, 1–100. There is no offset — pagination is limit-only.
string
default:"false"
true or false. When true, matches inside tool call inputs and tool results are included in the result list.

Search modes and degradation

The response always reports which mode actually ran (search_mode) and why, if it differs from what you requested (degrade_reason). A semantic or hybrid request degrades transparently to keyword rather than failing:
Scores use a different scale per mode and are not comparable across modes: in keyword mode the score is an integer count of substring matches; in semantic mode it is a similarity value; in hybrid mode it is a small rank-fusion fraction. Branch on search_mode before applying any threshold, and use scores only to order results within a single response. Scores are rounded to 4 decimals.

Response fields

string
The query as searched (trimmed).
string
The mode that actually ran: keyword, semantic, or hybrid. May differ from the requested mode.
string
none, semantic_unavailable, or below_relevance_floor.
array
Ranked hits. Each hit has conversation_id, message_index, role (user or assistant), timestamp, snippet (the matched text with surrounding context), score, cluster_id and cluster_name (the trace’s use-case cluster, or null), and conversation_summary (a one-line description of the trace: its latest task’s goal, else its stored summary from before summaries were retired, or null). Hits that resolve to a specific content block additionally carry unit_id, content_block_index, block_type, tool_name, and chunk_index.
object
Exact counts of distinct traces containing a literal (case-insensitive) match for the query — independent of the ranked page. matched_conversations covers the requested window; prior_window_matched_conversations covers the equal-length window immediately before it (null when time_range=all). Either can be null if the count query timed out — a missing number, never a fabricated zero.These two counts are literal-match counts in every mode, including semantic and hybrid, so they don’t describe the size of a semantic or hybrid result set. The object also carries:
  • mode: the mode that ran (the same value as search_mode).
  • matched_conversations_basis: always literal_substring.
  • candidate_conversations: the number of distinct traces in the ranked candidate set of the mode that ran, before paging. It comes from a bounded pool, so it isn’t a count over all your data. It is null when unknown.
  • note: a one-line explanation of the fields above.
object
limit (requested page size), returned (hits in this response), and has_more (true when the ranked candidate pool held more hits than the page). There is no offset; to see different results, narrow q, time_range, or user_id.

Example

To read the turns around the first hit:

Next steps

  • Traces — fetch windowed context around any search hit.
  • Signals — if you are hunting failures, the frustration and tool-failure endpoints already embed context.
  • CLI reference — moda traces search wraps this endpoint with the same modes.