Search Traces
Find local traces and inspect matching events from the CLI.
Use traces search when you know a word, error, file name, tool, or date range and need to find the trace that contains it. Search runs against your local Traces database.
Quick start
# Search trace metadata and default event text
traces search sidebar
# Return matching event rows instead of grouped traces
traces search 'timeout|connection refused' --result-level event
# Search shell output from tool results
traces search 'build failed' --event-type tool_result --tool bash --result-level event
# Inspect the event and nearby context
traces show <trace-id> --around-event 63 --before 3 --after 8Recommended workflow
-
Start with a small recent list when you need IDs or timestamps:
traces list --dir . --limit 20 -
Search with the narrowest useful filters:
traces search migration --dir . --since 7d --limit 20 -
Inspect bounded content instead of dumping a whole trace:
traces show <trace-id> --event-type user_message,agent_text --offset 1 --limit 40 -
Include tool calls/results only when you need commands, file paths, test output, or implementation evidence:
traces show <trace-id> --event-type tool_result --tool bash --around-event 63
For AI agents, run traces search-instructions before using list, search, and show. It prints compact guidance designed to keep context usage low.
How matching works
- Patterns are case-insensitive regular expressions by default.
- Use
--literalfor fixed substring search. - Default sources are
trace,event. - Default event types are
user_message,agent_text, anderror. - Tool calls, tool results, and agent thinking are excluded by default; request them explicitly with
--event-type. - Search only sees event text that has been saved locally.
traces show <id>can hydrate events from the native local session file, andtraces show <id> --remoteortraces sync <id>can pull remote content from the API.
Search options
| Flag | Description |
|---|---|
--literal | Treat the pattern as a fixed string instead of regex |
--case-sensitive | Match case exactly |
--source trace,event | Search trace metadata, saved event text, or both |
--event-type TYPES | Filter event rows (user_message, agent_text, agent_thinking, tool_call, tool_result, error) |
--tool NAMES | Filter tool_call/tool_result rows by tool name |
--result-level MODE | Use trace to group matches or event to return event hits |
--trace-id ID | Restrict search to one trace; comma-separated IDs are accepted |
--agent ID | Restrict search to one local agent ID |
--dir PATH | Restrict search to a directory/source path prefix |
--since 7d | Relative time filter (ms, s, m, h, d, w; defaults to milliseconds) |
--after DATE | Absolute lower time bound (date string or millisecond timestamp) |
--before DATE | Absolute upper time bound (date string or millisecond timestamp) |
--limit N | Limit returned matches |
--scan-traces N | Search budget: number of candidate traces to scan |
--scan-events-per-trace N | Search budget: number of event rows to scan per trace |
--json | JSON output |
--diagnostics | Include timing and output-size diagnostics |
--search-instructions | Print the same guidance as traces search-instructions |
--help, -h | Show search help |
Trace results vs event results
Use the default --result-level trace when you only need candidate trace IDs:
traces search renderer --source trace --limit 10Use --result-level event when you need the exact event number for a follow-up traces show --around-event call:
traces search renderer --source event --result-level event --limit 20
traces show <trace-id> --around-event <event-number> --before 5 --after 10Search budgets
--limit controls how many matches are returned. The scan budget flags control how much local history is searched before matches are returned.
Increase scan budgets only when recall is too narrow:
traces search database --scan-traces 1000 --scan-events-per-trace 100 --limit 20If output is too large, reduce --limit, add --dir, add --since, or search a specific trace with --trace-id.
Machine-readable output
traces search database --json --result-level event --limit 20JSON output is bounded by the same --limit and scan budget flags as human-readable output.
Related commands
traces listlists local traces and IDs.traces show <id>prints trace metadata or bounded event content.traces sync <id>downloads a remote trace into the local database.traces search-instructionsprints the recommended agent workflow.