> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thecontextcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces: the evidence behind every analysis

> How The Context Company renders a full agent run: model steps, tool calls, arguments, results, errors, latency, cost, and metadata.

A trace is the complete execution of a single [run](/concepts#runs). It is the primary evidence behind every [pattern](/analyze/patterns), [failure](/analyze/failures), [Insight Search](/analyze/insight-search) result, and [Recap](/analyze/recaps) 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](/concepts#tcc-metadata-keys) and any custom metadata you attached.
* **Session and identity.** The [session](/concepts#sessions), [user](/analyze/users-and-organizations), [organization](/analyze/users-and-organizations), and [agent](/concepts#agents) 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](/investigate/tutorial-silent-tool-failure).

## 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](/access-data/api#runs)
* Via `get_agent_run` on [MCP](/access-data/mcp#get_agent_run)

## 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](/access-data/mcp) for setup and full tool reference.

## Related

<CardGroup cols={2}>
  <Card title="Concepts" icon="cubes" href="/concepts">
    Runs, steps, and tool calls.
  </Card>

  <Card title="What TCC captures" icon="database" href="/what-tcc-captures">
    Every field recorded per trace.
  </Card>

  <Card title="Silent tool failure tutorial" icon="bug" href="/investigate/tutorial-silent-tool-failure">
    A trace-driven walkthrough.
  </Card>

  <Card title="MCP" icon="plug" href="/access-data/mcp">
    Traces in your coding agent.
  </Card>
</CardGroup>