> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API Access to Guardrail Metrics
> Query Gateway guardrail evaluation metrics for outcome and latency analytics via API.
The **Gateway Guardrail Metrics Query API** provides a flexible way to query guardrail evaluations: which guardrail ran on which entity (input or output), what the outcome was (pass, fail, error), and how long it took. You can retrieve either **distribution** (aggregated) or **timeseries** results with powerful filtering and grouping.
This page covers `datasource: "guardrailMetrics"`. For other datasources, see the sibling pages for [Model](/docs/ai-gateway/fetch-model-metrics), [MCP](/docs/ai-gateway/fetch-mcp-metrics), [Cache](/docs/ai-gateway/fetch-cache-metrics), [Routing](/docs/ai-gateway/fetch-routing-metrics), and [Agent](/docs/ai-gateway/fetch-agent-metrics) metrics.
### Access control
* **Tenant admins:** Can query metrics for the entire organization (tenant-wide).
* **Users:** Can query their own data and their teams' data.
* **Virtual accounts:** Can query their own data and their teams' data; with tenant-admin permissions, they can access tenant-wide data.
The server applies RBAC automatically; callers don't pass any RBAC fields.
## Contents
| Section | Description |
| --------------------------------------------------------------------------------------- | ---------------------------------------------- |
| [Overview](/docs/ai-gateway/fetch-guardrail-metrics) | Authentication, quick start, and API reference |
| [Filtering](/docs/ai-gateway/fetch-guardrail-metrics-filtering) | Filter operators, fields, and combinations |
| [Distribution examples](/docs/ai-gateway/fetch-guardrail-metrics-examples-distribution) | Aggregated (distribution) query examples |
| [Timeseries examples](/docs/ai-gateway/fetch-guardrail-metrics-examples-timeseries) | Time-bucketed (timeseries) query examples |
| [Response format](/docs/ai-gateway/fetch-guardrail-metrics-response) | Response JSON structure and error responses |
## Authentication
You need to authenticate with your TrueFoundry API key. You can use either a Personal Access Token **(PAT)** or Virtual Account Token **(VAT)**.
To generate an API key:
1. **Personal Access Token (PAT)**: Go to Access → Personal Access Tokens in your TrueFoundry dashboard
2. **Virtual Account Token (VAT)**: Go to Access → Virtual Account Tokens (requires admin permissions)
For detailed authentication setup, see our [Authentication guide](/docs/ai-gateway/authentication).
## Quick Start
### Distribution query
Counts and latency percentiles per guardrail and outcome, restricted to input-scope evaluations:
```python theme={"dark"}
import requests
response = requests.post(
"https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "count", "column": "guardrailName"},
{"type": "p50", "column": "latencyMs"},
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName", "guardrailResult"],
"filters": [
{"fieldName": "appliedOnEntityScope", "operator": "IN", "value": ["input"]}
]
}
)
print(response.json())
```
### Timeseries query
Hourly counts and p99 latency per guardrail:
```python theme={"dark"}
import requests
response = requests.post(
"https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query",
headers={
"Authorization": "Bearer ",
"Content-Type": "application/json"
},
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "timeseries",
"interval": "1 hour",
"aggregations": [
{"type": "count", "column": "guardrailName"},
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName"]
}
)
print(response.json())
```
## API reference
### Endpoint
```
POST https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query
```
Post JSON to this endpoint with `Authorization: Bearer ` and `Content-Type: application/json`.
### Request parameters
ISO 8601 timestamp marking the **inclusive** lower bound of the query window.
ISO 8601 timestamp marking the **exclusive** upper bound of the query window.
The data source to query. Use `"guardrailMetrics"` for Gateway guardrail metrics.
The type of query to execute:
* `"distribution"`: returns aggregated rows (one row per `groupBy` combination).
* `"timeseries"`: returns time-bucketed rows. Requires `interval`.
Array of `{ type, column }` objects describing the aggregations to compute. When omitted, only the implicit `total = COUNT(*)` is returned.
**Supported aggregation types**
| Type | Description |
| ------------------------------------------------------------- | ------------------------------------------------------------- |
| `sum` | Sum of values |
| `count` | Non-null count of the column |
| `countDistinct` | Distinct count |
| `min` | Minimum value |
| `max` | Maximum value |
| `avg` | Average |
| `p5`, `p10`, `p25`, `p50`, `p75`, `p90`, `p95`, `p99`, `p999` | Percentiles (approximate) |
| `rateSum`, `rateAvg`, `rateMin`, `rateMax` | Rates normalised by the interval in seconds (timeseries only) |
| `ratePerMinute` | Value divided by the interval in minutes (timeseries only) |
**Supported aggregation columns**
| Column | Supported aggregation types | Notes |
| ----------- | ------------------------------ | ---------------------------------- |
| `latencyMs` | all scalar and all percentiles | Guardrail evaluation latency in ms |
Array of field names to group results by. Custom metadata keys are supported with a `metadata.` prefix.
**Available group-by fields**
| Field | Notes |
| ---------------------- | --------------------------------------------------------------- |
| `guardrailName` | The configured guardrail's name |
| `appliedOnEntityScope` | Where the guardrail ran (e.g. `input`, `output`) |
| `guardrailResult` | Outcome (e.g. `pass`, `fail`, `error`) |
| `userEmail` | Group by user (response key: `createdBySubjectSlug`) |
| `virtualaccount` | Group by virtual account (response key: `createdBySubjectSlug`) |
| `team` | Unnests the `Teams` array |
| `createdBySubjectType` | Distinguishes `user` vs `virtualaccount` |
| `metadata.` | Group by a custom metadata key |
When `groupBy` contains `userEmail` (without `virtualaccount`), the server auto-injects `WHERE CreatedBySubjectType = 'user'`. `virtualaccount` alone auto-injects `'virtualaccount'`. When both appear, scope it yourself with `createdBySubjectType` if needed.
Array of filter objects, AND-combined. See [Filtering](/docs/ai-gateway/fetch-guardrail-metrics-filtering) for the full operator reference and the per-field allow-list.
**Required for timeseries queries.** Bucket size as ` `, where `` is one of `second`, `minute`, `hour`, `day`, `week`, `month`, `year` (with or without a trailing `s`). Examples: `"30 second"`, `"5 minute"`, `"1 hour"`, `"1 day"`. Compound expressions like `"1 hour 30 minute"` are rejected.
**Deprecated alias for `interval`.** Accepts a positive integer number of seconds. Prefer `interval` in new code. If both are provided, `interval` wins.