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
The search query, 1–500 characters. Leading and trailing whitespace is trimmed; a whitespace-only query returns
400.keyword, semantic, or hybrid. Keyword matches literal substrings; semantic matches by meaning; hybrid fuses both. See Search modes.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.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.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).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:
Response fields
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.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 assearch_mode).matched_conversations_basis: alwaysliteral_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 isnullwhen unknown.note: a one-line explanation of the fields above.
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
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 searchwraps this endpoint with the same modes.