Get Traces
get_tracesRetrieve historical agent-execution traces with filters, pagination, and optional dashboard summary. Read-only query for analyzing past runs, failures, and performance trends.
Instructions
Query stored agent-execution traces with filters, pagination, and optional dashboard summary.
Sibling tools — log_trace creates traces, delete_trace removes a single trace, evaluate_output / evaluate_with_llm_judge / verify_citations score them, list_rules / deploy_rule / delete_rule manage the custom-rule lifecycle. get_traces is the READ path for historical agent executions — never mutates anything.
Behavior. Read-only: never mutates storage, never calls external services. Idempotent: repeated calls with the same args return consistent results (new traces logged after the call obviously show up on subsequent calls). Tenant-scoped: queries only the caller's tenant rows (LOCAL_TENANT in OSS). Paginates results (default limit 50, max 1000). Rate-limited to 20 req/min on HTTP MCP, unlimited on stdio.
Output shape. Returns JSON: { "traces": [{...traceRow}], "total": number, "limit": number, "offset": number, "summary"?: { total_traces, avg_latency_ms, total_cost_usd, error_rate, eval_pass_rate, traces_per_hour, top_agents } }. Each trace row includes trace_id, agent_name, framework, input, output, tool_calls, latency_ms, token_usage, cost_usd, metadata, timestamp. summary only included when include_summary: true.
Use when you need historical data: investigating a past failure, computing quality trends, comparing agents, or feeding an analytics job. Set agent_name / framework / since / until to narrow the query. Set min_score / max_score to surface outliers. Set sort_by: "cost_usd" + sort_order: "desc" to find the most expensive traces. Set include_summary: true when you want dashboard-style aggregates in one round-trip.
Don't use to score a trace (use evaluate_output). Don't use to create a trace (use log_trace). Don't use as a live event stream — it's a query, not a subscription; poll with exponential backoff or use the dashboard's SSE endpoint for real-time.
Parameters. limit defaults to 50, max 1000 (anything higher returns 400). offset is zero-based pagination. min_score / max_score filter on the LATEST eval per trace, not all evals (so a trace with one failing + one passing eval may or may not match depending on which landed last). Combining since + sort_by="latency_ms" + sort_order="desc" is the canonical "find slow recent traces" query. include_summary returns dashboard-style aggregates in the SAME response (saves a round-trip; use true for dashboard ingest, false for analytics queries that don't need them). agent_name and framework are exact-match (no wildcards in v0.4). Defaults: limit=50, offset=0, sort_by="timestamp", sort_order="desc", include_summary=false.
Error modes. Returns 400 on invalid sort_by / sort_order (Zod enum). Returns 400 if limit > 1000. Returns 429 when HTTP rate limit exceeded. Storage failures propagate as 500. Empty result with total: 0 on no matches (not an error).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Results per page (default 50, max 1000 — values >1000 return 400) | |
| since | No | ISO timestamp lower bound — return traces with timestamp >= this | |
| until | No | ISO timestamp upper bound — return traces with timestamp < this | |
| offset | No | Zero-based pagination offset — skip first N results | |
| sort_by | No | Sort by timestamp | latency_ms | cost_usd (default timestamp) | timestamp |
| framework | No | Filter by agent framework — exact match (e.g., langchain, autogen) | |
| max_score | No | Maximum eval score filter (0..1) — applied to LATEST eval per trace | |
| min_score | No | Minimum eval score filter (0..1) — applied to LATEST eval per trace, not all evals | |
| agent_name | No | Filter by agent name — exact match (no wildcards in v0.4) | |
| sort_order | No | Sort order: asc | desc (default desc — most recent / highest first) | desc |
| include_summary | No | Include dashboard summary stats in same response — saves a round-trip when ingesting for dashboards |