# Metrics

The Metrics API provides access to time-series DQ metric history for your monitored assets. Use this to build custom dashboards, export data, or analyze trends outside of the Telmai UI.

***

## GET /api/metrics

Query metric history for a monitor or asset.

**Permission:** `metrics:read` (all authenticated users)

**Query parameters:**

| Parameter    | Type    | Description                               |
| ------------ | ------- | ----------------------------------------- |
| `monitorId`  | string  | Filter to a specific monitor              |
| `assetId`    | string  | Filter to all monitors for an asset       |
| `from`       | ISO8601 | Start of time range                       |
| `to`         | ISO8601 | End of time range                         |
| `metricName` | string  | Specific metric (e.g., `dq.completeness`) |

**Response (200):**

```json
{
  "data": [
    {
      "timestamp": "2026-03-24T09:00:00Z",
      "monitorId": "uuid",
      "assetId": "uuid",
      "metricName": "dq.completeness",
      "value": 98.5,
      "attributes": {
        "column": "customer_id",
        "threshold": 95
      },
      "breach": false
    },
    {
      "timestamp": "2026-03-24T03:00:00Z",
      "monitorId": "uuid",
      "assetId": "uuid",
      "metricName": "dq.completeness",
      "value": 82.1,
      "attributes": {
        "column": "customer_id",
        "threshold": 95
      },
      "breach": true
    }
  ]
}
```

***

## Metric Names

| Metric Name       | Description               | Unit                       |
| ----------------- | ------------------------- | -------------------------- |
| `dq.record_count` | Table row count           | rows                       |
| `dq.freshness`    | Time since last update    | hours                      |
| `dq.completeness` | Non-null ratio per column | % (0–100)                  |
| `dq.schema`       | Schema change detected    | 0 = no change, 1 = changed |
| `dq.custom_sql`   | Custom SQL query result   | user-defined               |

***

## Notes

* `breach: true` means the metric value crossed the configured threshold at that point in time
* Metric history is retained for the duration configured on your Telmai plan
* Time range queries are inclusive on both ends


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fabric-docs.telm.ai/api-reference/metrics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.