> ## 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.

# Failures: recurring errors across production

> How The Context Company groups run and tool-call errors into recurring failure patterns you can rank, filter, and investigate.

Failures answer the question: **what recurring problems keep happening in production?**

Where [Patterns](/analyze/patterns) monitor behaviors you already know to watch for, Failures group runtime errors from the execution itself: runs that errored, tool calls that returned errors, and the metadata around them.

## What is captured

For every run, The Context Company records status, error class, and status message at the run, step, and tool-call level (see [what The Context Company captures](/what-tcc-captures)). Failures are computed from those errors.

Each failure includes:

* Entity type (`run` or `tool_call`)
* Aggregated event count (how often it has occurred in the selected range)
* First seen and last seen timestamps
* Status: `active`, `resolved`, or `ignored`
* Links into the affected runs and traces

## Using failures

Failures live under the runs / dashboard views and are available programmatically through the [REST API](/access-data/api).

Typical workflow:

<Steps>
  <Step title="Rank by frequency or recency">
    Sort by event count to find the biggest sources of production error, or by last-seen to find what is spiking right now.
  </Step>

  <Step title="Filter by entity type">
    Separate run-level errors (the agent as a whole failed) from `tool_call` errors (a specific tool returned an error).
  </Step>

  <Step title="Open an affected run">
    Every failure links to the runs that produced it. Open one to see the full [trace](/investigate/traces): the model steps, tool calls, arguments, results, and where the error occurred.
  </Step>

  <Step title="Investigate with Insight Search">
    Use [Insight Search](/analyze/insight-search) to ask "which tools were called just before this error", "which users are hitting it", or "did this start with a specific release".
  </Step>

  <Step title="Mark resolved or ignored">
    Set a failure's status so it stops surfacing on active dashboards once fixed or intentionally deprioritized.
  </Step>
</Steps>

## Programmatic access

The REST API exposes failures directly:

```bash theme={null}
GET /v1/failures?range=1d&order_by=events&direction=desc
```

Filter by `entity_type` (`run` or `tool_call`) or `status` (`active`, `resolved`, `ignored`). Fetch a single failure with `GET /v1/failures/:failureId`. See the [API reference](/access-data/api#failures).

The same data is available from [MCP](/access-data/mcp) via Insight Search, which lets your coding agent pull the current top failures and their affected runs directly into its context.

## Failures vs. patterns

|                   | Failures                                  | Patterns                                            |
| ----------------- | ----------------------------------------- | --------------------------------------------------- |
| **Question**      | What recurring errors are happening?      | Is a known behavior happening?                      |
| **Source**        | Run and tool-call errors from execution   | AI classifier over conversation + metadata          |
| **Configuration** | Automatic grouping, no setup              | Built-in signals + user-defined classifiers         |
| **Applies to**    | All runs                                  | Conversational runs only                            |
| **Best for**      | Runtime errors, tool failures, exceptions | Frustration, confusion, workflow-specific behaviors |

Use both. Failures catch runtime problems; patterns catch behavioral ones that the transcript reveals.

## Limitations

* Failures aggregate around error classes and messages captured on the run, step, or tool call. Silent failures (the agent claims success while a tool returned an error) surface when the tool call itself errored; if the agent silently swallowed the error before the tool returned an error status, use a [pattern](/analyze/patterns) or Insight Search to catch it.
* Grouping is heuristic; use Insight Search to explore boundaries between clusters.

## Related

<CardGroup cols={2}>
  <Card title="Traces" icon="diagram-project" href="/investigate/traces">
    Open a run to see the exact model step or tool call that failed.
  </Card>

  <Card title="Patterns" icon="magnifying-glass" href="/analyze/patterns">
    Detect behavioral signals that are not raw errors.
  </Card>

  <Card title="Tools and models" icon="wrench" href="/analyze/tools-and-models">
    Which tools contribute the most to failure rate.
  </Card>

  <Card title="REST API" icon="code" href="/access-data/api#failures">
    Query and update failures programmatically.
  </Card>
</CardGroup>