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

# Metrics

> Aggregated views across traces.

**Metrics** are rolling aggregations over traces. TruLayer computes them continuously and surfaces them in the dashboard and via the `/v1/metrics` endpoint.

## Built-in metrics

| Metric                                      | Description                                                              |
| ------------------------------------------- | ------------------------------------------------------------------------ |
| `error_rate`                                | Fraction of traces that ended in error over the window                   |
| `latency_p50`, `latency_p95`, `latency_p99` | Trace latency percentiles                                                |
| `total_cost`                                | Sum of `(prompt_tokens + completion_tokens) × model_price` across traces |
| `trace_count`                               | Number of traces in the window                                           |
| `feedback_good_rate`                        | Fraction of feedback-labeled traces with `label="good"`                  |

## Query

<CodeGroup>
  ```python Python theme={null}
  import trulayer
  from datetime import datetime, timedelta

  client = trulayer.get_client()
  metrics = client.get_metrics(
      project_id="rag-app",
      from_time=datetime.utcnow() - timedelta(hours=1),
      to_time=datetime.utcnow(),
  )
  print(metrics.error_rate, metrics.latency_p95, metrics.total_cost)
  ```

  ```typescript TypeScript theme={null}
  const metrics = await tl.getMetrics({
    projectId: "rag-app",
    from: new Date(Date.now() - 60 * 60 * 1000),
    to: new Date(),
  });
  console.log(metrics.errorRate, metrics.latencyP95, metrics.totalCost);
  ```

  ```bash curl theme={null}
  curl "https://api.trulayer.ai/v1/metrics?project_id=rag-app&from=2026-04-19T00:00:00Z&to=2026-04-19T23:59:59Z" \
    -H "Authorization: Bearer $TRULAYER_API_KEY"
  ```
</CodeGroup>

## In the dashboard

The **Metrics** page shows these metrics as time-series charts. You can:

* Filter by project, model, or tag
* Overlay multiple metrics on the same axis
* Drill from any point into the underlying traces

## Project-scoped metrics

`GET /v1/projects/{id}/metrics` returns a single scalar metric scoped to one project over a fixed window. This endpoint complements the trace-level `/v1/metrics` endpoint — it answers questions about control-loop behaviour at the project level rather than about individual trace latency or cost.

### Supported metrics

| Metric          | Description                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `retry_cap_hit` | Number of traces in the window where a policy hit its `max_retry_depth` cap and auto-escalated to the HITL pending-approval queue. |

### Parameters

| Parameter | Required | Description                                           |
| --------- | -------- | ----------------------------------------------------- |
| `metric`  | Yes      | Metric name. Currently only `retry_cap_hit` is valid. |
| `window`  | Yes      | Aggregation window. One of `7d` or `30d`.             |

### Response shape

```json theme={null}
{
  "metric": "retry_cap_hit",
  "value": 12,
  "window": "30d"
}
```

`value` is always an integer count. The endpoint returns `0` (not `null`) when no traces match in the window.

### Auth

Requires a Clerk session (viewer role or above) or an API key with the `query` scope.

### Example

```bash theme={null}
curl "https://api.trulayer.ai/v1/projects/proj_01j.../metrics?metric=retry_cap_hit&window=30d" \
  -H "Authorization: Bearer $TRULAYER_API_KEY"
```

Use `retry_cap_hit` alongside your policy's `max_retry_depth` setting to tune the escalation threshold: if the count is high, consider raising the depth cap or adjusting the trigger condition to reduce spurious retries.

## Cost calculation

TruLayer maintains a per-model price table for major providers (OpenAI, Anthropic, Google, Cohere). Cost is computed at ingest time and stored on the trace so historical reports are stable even when upstream prices change.

For custom models or providers, attach `metadata.cost_usd` to the LLM span and TruLayer will use it instead of the price table.