Traces: the evidence behind every analysis

A trace is the complete execution of a single run. It is the primary evidence behind every pattern, failure, Insight Search result, and Recap finding. Traces are not an engineering-debugging appendix. They are what makes execution-aware analytics possible. When Insight Search claims “the agent said it processed the refund but the tool returned an error,” the trace is what proves it.

​

What a trace shows

For every run, the trace view includes:

• Prompt and response. The user’s input and the agent’s final output.
• Model steps. Each LLM request and response inside the run, in order.
• Tool calls. For each step, the tools the model invoked, with:
  • Tool name
  • Full arguments passed
  • Full result returned
  • Success or error status
  • Latency
• Errors and status messages. Attached at whichever level failed (run, step, or tool call).
• Tokens and cost. Per model step, aggregated per run.
• Timings. Duration of each step and tool call.
• Metadata. Reserved tcc.* keys and any custom metadata you attached.
• Session and identity. The session, user, organization, and agent the run belongs to.

​

Example: a silent tool failure

A conversation looks successful because the agent tells the user “your refund has been processed.” The trace shows that issueRefund returned { error: "unknown_customer" } and the model continued as if it had succeeded.

Execution-level telemetry makes this failure observable even if the user never complains. Walk through the full workflow in the silent tool failure tutorial.

​

How traces feed the rest of the product

• Patterns classify against the transcript and metadata, and link to matching traces for evidence.
• Failures group run and tool-call errors surfaced by trace data.
• Insight Search queries structured fields of the trace (steps, tools, arguments, results, errors, cost, latency) and joins them with sessions, users, orgs, and feedback.
• Recaps cite traces as the evidence behind every trend and issue.
• MCP returns traces (full or summary) to your coding agent so it can propose a code change against the exact failure.

​

Opening a trace

Traces can be opened from anywhere:

• The runs list on the dashboard
• Any pattern’s detail page
• Any failure’s affected runs
• Any Insight Search or Recap result
• Programmatically via GET /v1/runs/:runId on the REST API
• Via get_agent_run on MCP

​

MCP: pull traces into your coding agent

The MCP integration exposes traces directly to Cursor, Claude Code, and other MCP clients. Ask your agent:

Pull the trace for run abc123, find where the tool call failed, and propose a code fix.

See MCP for setup and full tool reference.

​

Related