Get Traces
get_tracesQuery stored traces with exact-match, score-range, time and full-text filters, plus pagination, sorting and optional dashboard summary. Returns ranked snippets and totals for agent observability.
Instructions
Query stored traces with filters, pagination and sorting; optionally with the dashboard summary.
What it does. Read-only, local. Exact-match agent_name and framework, inclusive since and until, min_score and max_score on each trace's latest evaluation, and q: full-text search, ranked, with a snippet. limit is 1..1000 (default 50). A crossed range is refused, never returned as an empty page. Full detail: iris://capabilities.
When not to use it. To score a trace (evaluate_output) or create one (log_trace). As a live stream: poll with backoff.
Returns. JSON: untrusted, traces, total, limit, offset, summary, search.
Errors. IRIS_STORAGE_ERROR. Out-of-range bounds are refused, naming the values; no match is total 0, not an error. Failures return {"error":{code,message,recovery}} with isError; follow recovery.
Siblings. log_trace — record an execution; evaluate_output — score one output; delete_trace — remove one trace.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Full-text search over input, output, tool-call values, metadata values and span attribute and event values. Every word must appear; "quoted phrase"; word* for a prefix of 3+ characters (1 for CJK). Case and accents ignored. At most 16 terms, 4 of them prefixes | |
| limit | No | Results per page (default 50, max 1000 — values above are rejected) | |
| since | No | Inclusive lower bound, an ISO 8601 timestamp or date; anything else is rejected | |
| until | No | ISO 8601 timestamp (or date) upper bound — return traces with timestamp <= this; must not be earlier than `since` | |
| offset | No | Zero-based pagination offset — skip first N results (non-negative integer) | |
| session | No | Filter by session id — the turns of one conversation, as logged with session_id | |
| sort_by | No | Sort by timestamp | latency_ms | cost_usd | relevance (default relevance with q, else timestamp) | |
| framework | No | Filter by agent framework — exact match (e.g., langchain, autogen) | |
| max_score | No | Maximum eval score filter (0..1; values outside are rejected) — applied to LATEST eval per trace | |
| min_score | No | Minimum score (0..1) of each trace's latest evaluation; at most max_score | |
| agent_name | No | Filter by agent name — exact match (no wildcards) | |
| sort_order | No | Sort order: asc | desc (default desc — most recent / highest first) | desc |
| include_text | No | Return each stored text whole. By default each is cut to 500 characters, and the trace's cut lists what was cut with its full length; iris://traces/{trace_id} reads one trace whole | |
| include_summary | No | Include dashboard summary stats in same response — saves a round-trip when ingesting for dashboards |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | Yes | ||
| total | Yes | ||
| offset | Yes | ||
| search | No | ||
| traces | Yes | ||
| summary | No | ||
| untrusted | No |