> ## 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.
# 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.
All requests go to a single endpoint:
```
POST https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query
```
Send JSON with `Authorization: Bearer ` and `Content-Type: application/json`.
## Access control
Access to metrics is governed by the **data access rules configured by your tenant**. The server applies these rules automatically based on the caller's identity—you don't pass any RBAC or scoping fields in the request. What a caller can query (their own data, their team's data, or tenant-wide data) depends entirely on the rules an admin has set up.
See [Configure Data Access](/docs/ai-gateway/data-access) for how these rules are defined and evaluated.
## Authentication
Authenticate with your TrueFoundry API key. You can use either a Personal Access Token **(PAT)** or Virtual Account Token **(VAT)**.
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
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())
```
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
Post JSON to the endpoint above 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.
| 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) |
| 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.
| 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](#filtering) below 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.
## Filtering
Filters narrow down the rows that go into each aggregation and group. They are AND-combined; there is no OR-group support. The server enforces a per-field operator allow-list, so the exact subset of operators you can use depends on the field.
For standard datasource fields, use `fieldName`:
```json theme={"dark"}
{
"fieldName": "guardrailName",
"operator": "IN",
"value": ["pii-detector", "toxicity-filter"]
}
```
For custom request-metadata keys, use `metadataKey`. Works on every datasource:
```json theme={"dark"}
{
"metadataKey": "environment",
"operator": "IN",
"value": ["production"]
}
```
The guardrail-specific string fields (`guardrailName`, `appliedOnEntityScope`, `guardrailResult`) accept only a narrow set of string operators (`IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`). `EQUAL` and `NOT_EQUAL` are only supported on subject fields and `conversationID`.
| Field | Type | Allowed operators |
| -------------------------------- | ------ | ------------------------------------------------------------------------------- |
| `guardrailName` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `appliedOnEntityScope` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `guardrailResult` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `userEmail` | string | full string operator set (no `IS_NULL`) |
| `virtualAccount` | string | full string operator set (no `IS_NULL`) |
| `team` | array | `ARRAY_HAS_ANY`, `ARRAY_HAS_NONE` |
| `latencyMs` | number | `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_EQUAL`, `LESS_THAN_EQUAL`, `BETWEEN` |
| `conversationID` | string | full string operator set |
| `metadataKey` / `metadata.` | string | full string operator set |
**String field operators**
| Operator | Description | Example value |
| ------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------- |
| `EQUAL` | Exact match | `"alice@example.com"` |
| `NOT_EQUAL` | Not equal to value | `"bot@example.com"` |
| `IN` | Match any value in the list | `["pii-detector", "toxicity-filter"]` |
| `NOT_IN` | Exclude values in the list | `["deprecated-guardrail"]` |
| `STRING_CONTAINS` | Contains substring | `"pii"` |
| `STRING_NOT_CONTAINS` | Does not contain substring | `"deprecated"` |
| `STRING_STARTS_WITH` | Starts with prefix | `"pii-"` |
| `STRING_NOT_STARTS_WITH` | Does not start with prefix | `"internal-"` |
| `STRING_ENDS_WITH` | Ends with suffix | `"-filter"` |
| `STRING_NOT_ENDS_WITH` | Does not end with suffix | `"-deprecated"` |
| `IS_NULL` | `true` matches rows where the field is unset; `false` matches rows where it is set | `true` |
**Numeric field operators**
| Operator | Description | Example value |
| -------------------- | ---------------------------------------------------------------------------------- | ----------------- |
| `EQUAL` | Exact match | `1000` |
| `NOT_EQUAL` | Not equal to value | `0` |
| `IN` | Match any value in the list | `[100, 200, 300]` |
| `NOT_IN` | Exclude values in the list | `[0]` |
| `GREATER_THAN` | Strictly greater than | `1000` |
| `LESS_THAN` | Strictly less than | `5000` |
| `GREATER_THAN_EQUAL` | Greater than or equal to | `100` |
| `LESS_THAN_EQUAL` | Less than or equal to | `1000` |
| `BETWEEN` | Between two values (inclusive) | `[500, 5000]` |
| `IS_NULL` | `true` matches rows where the field is unset; `false` matches rows where it is set | `true` |
**Array field operators (used by `team`)**
| Operator | Description | Example value |
| ---------------- | ---------------------------------------------- | ----------------------------- |
| `ARRAY_HAS_ANY` | Match if the array contains any of the values | `["team-alpha", "team-beta"]` |
| `ARRAY_HAS_NONE` | Match if the array contains none of the values | `["excluded-team"]` |
**Custom metadata filtering and grouping.** Every datasource supports filtering and grouping by custom request-metadata keys:
* **Filter:** `{ "metadataKey": "environment", "operator": "EQUAL", "value": "prod" }`
* **Group:** include `"metadata.environment"` in the `groupBy` array.
Metadata fields are treated as strings; use the string field operators above.
**Implicit team unnesting.** When `team` is in `groupBy` (or used as the column of an aggregation), the server transparently UNNESTs the `Teams` array CTE before applying RBAC. Callers don't need to do anything extra. Rows whose `Teams` array is NULL or empty drop out naturally.
**Combining multiple filters.** Filters are AND-combined:
```json theme={"dark"}
{
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"filters": [
{"fieldName": "appliedOnEntityScope", "operator": "IN", "value": ["input"]},
{"fieldName": "guardrailResult", "operator": "IN", "value": ["fail", "error"]},
{"fieldName": "latencyMs", "operator": "LESS_THAN", "value": 1000},
{"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
],
"groupBy": ["guardrailName", "guardrailResult"]
}
```
## Query examples
Every example posts a JSON body to the endpoint above. To keep the snippets short, only the `json` body is shown; the request wrapper is identical to the [Quick start](#quick-start).
### Distribution examples
Counts grouped by guardrail and outcome, useful for spotting guardrails that fail most often:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "count", "column": "guardrailName"}
],
"groupBy": ["guardrailName", "guardrailResult"]
}
```
p50, p90, and p99 grouped by guardrail, restricted to output-scope evaluations:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "p50", "column": "latencyMs"},
{"type": "p90", "column": "latencyMs"},
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName"],
"filters": [
{"fieldName": "appliedOnEntityScope", "operator": "IN", "value": ["output"]}
]
}
```
Volume and average latency of evaluations slower than 500 ms, grouped by guardrail:
```python theme={"dark"}
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": "avg", "column": "latencyMs"}
],
"groupBy": ["guardrailName"],
"filters": [
{"fieldName": "latencyMs", "operator": "GREATER_THAN", "value": 500}
]
}
```
Restrict to failed evaluations, grouped by guardrail and scope:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "count", "column": "guardrailName"}
],
"groupBy": ["guardrailName", "appliedOnEntityScope"],
"filters": [
{"fieldName": "guardrailResult", "operator": "IN", "value": ["fail"]}
]
}
```
Counts by team and a custom metadata key, restricted via team array filter:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "count", "column": "guardrailName"}
],
"groupBy": ["team", "metadata.environment"],
"filters": [
{"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha", "team-beta"]}
]
}
```
How many unique guardrails ran on input vs output:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "distribution",
"aggregations": [
{"type": "countDistinct", "column": "guardrailName"}
],
"groupBy": ["appliedOnEntityScope"]
}
```
Use `IN` on `guardrailName` to focus on a subset:
```python theme={"dark"}
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": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName", "guardrailResult"],
"filters": [
{"fieldName": "guardrailName", "operator": "IN", "value": ["pii-detector", "toxicity-filter"]}
]
}
```
### Timeseries examples
Every timeseries query must include `interval` (or the deprecated `intervalInSeconds`). Buckets are expressed as ` ` strings like `"5 minute"`, `"1 hour"`, or `"1 day"`.
Total guardrail evaluations per hour:
```python theme={"dark"}
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"}
]
}
```
Track p99 evaluation latency per scope (input / output) bucket-by-bucket:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "timeseries",
"interval": "1 hour",
"aggregations": [
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["appliedOnEntityScope"]
}
```
Track per-guardrail failure rate over time:
```python theme={"dark"}
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"}
],
"groupBy": ["guardrailName"],
"filters": [
{"fieldName": "guardrailResult", "operator": "IN", "value": ["fail"]}
]
}
```
Fine-grained breakdown to investigate a regression:
```python theme={"dark"}
json={
"startTs": "2026-04-21T14:00:00.000Z",
"endTs": "2026-04-21T16:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "timeseries",
"interval": "5 minute",
"aggregations": [
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName"]
}
```
Daily evaluation volume per guardrail across a 7-day window:
```python theme={"dark"}
json={
"startTs": "2026-04-14T00:00:00.000Z",
"endTs": "2026-04-21T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "timeseries",
"interval": "1 day",
"aggregations": [
{"type": "count", "column": "guardrailName"}
],
"groupBy": ["guardrailName"]
}
```
Focus on a few guardrails of interest:
```python theme={"dark"}
json={
"startTs": "2026-04-21T00:00:00.000Z",
"endTs": "2026-04-22T00:00:00.000Z",
"datasource": "guardrailMetrics",
"type": "timeseries",
"interval": "1 hour",
"aggregations": [
{"type": "p99", "column": "latencyMs"}
],
"groupBy": ["guardrailName"],
"filters": [
{"fieldName": "guardrailName", "operator": "IN", "value": ["pii-detector", "toxicity-filter"]}
]
}
```
Per-team guardrail activity over time:
```python theme={"dark"}
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"}
],
"groupBy": ["team"],
"filters": [
{"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
]
}
```
## Response format
Every successful response has the same outer shape:
```json theme={"dark"}
{
"data": {
"dataPoints": [
{
"startTimestamp": "2026-04-29T12:00:00.000Z",
"endTimestamp": "2026-04-29T13:00:00.000Z",
"total": 1234,
"": 0,
"": "value-or-null"
}
]
}
}
```
* **`total`**: implicit `COUNT(*)` for the row. Always present.
* **``**: one key per requested aggregation. The key is `` in camelCase (e.g. `countGuardrailName`, `p99LatencyMs`).
* **``**: one key per `groupBy` entry. The key is the lowerCamelCase form of the underlying column. Two special mappings:
* `userEmail` and `virtualaccount` both map to `createdBySubjectSlug` in the response.
* `team` maps to `team` (the value is a single unnested scalar, not an array).
All other `groupBy` keys preserve their lowerCamelCase name.
* **`startTimestamp`**: present only for timeseries responses. Bucket start as an ISO 8601 timestamp string (e.g. `"2026-04-29T12:00:00.000Z"`). Distribution responses omit it.
* **`endTimestamp`**: present only for timeseries responses. Bucket end as an ISO 8601 timestamp string, equal to the next bucket's `startTimestamp` (e.g. `"2026-04-29T13:00:00.000Z"`). Distribution responses omit it.
```json theme={"dark"}
{
"data": {
"dataPoints": [
{
"guardrailName": "pii-detector",
"guardrailResult": "pass",
"total": 980,
"countGuardrailName": 980,
"p50LatencyMs": 42.0,
"p99LatencyMs": 215.5
},
{
"guardrailName": "pii-detector",
"guardrailResult": "fail",
"total": 60,
"countGuardrailName": 60,
"p50LatencyMs": 48.5,
"p99LatencyMs": 240.0
},
{
"guardrailName": "toxicity-filter",
"guardrailResult": "pass",
"total": 720,
"countGuardrailName": 720,
"p50LatencyMs": 80.2,
"p99LatencyMs": 410.0
}
]
}
}
```
```json theme={"dark"}
{
"data": {
"dataPoints": [
{
"startTimestamp": "2026-04-21T00:00:00.000Z",
"endTimestamp": "2026-04-21T01:00:00.000Z",
"guardrailName": "pii-detector",
"total": 42,
"countGuardrailName": 42,
"p99LatencyMs": 220.0
},
{
"startTimestamp": "2026-04-21T01:00:00.000Z",
"endTimestamp": "2026-04-21T02:00:00.000Z",
"guardrailName": "pii-detector",
"total": 58,
"countGuardrailName": 58,
"p99LatencyMs": 245.5
}
]
}
}
```
If `groupBy` is empty or omitted, the response collapses to a single row (or one row per timeseries bucket) summarising every guardrail evaluation inside the window.
### Error responses
A malformed query returns `400 Bad Request`:
```json theme={"dark"}
{
"statusCode": 400,
"message": "Invalid query",
"details": ["..."]
}
```
Common causes of `400`:
* Operator not allowed on this field, for example, `EQUAL` on `guardrailName` (it supports only `IN`, `NOT_IN`, and `STRING_*` operators).
* Missing required `value` (or wrong shape, e.g. scalar where array is expected for `IN` / `BETWEEN`).
* Unknown field name for the datasource.
* Invalid `interval` format (compound expressions, unrecognised unit, non-positive integer).
* Missing required `interval` for a timeseries query.
Other status codes:
* `401 Unauthorized`: missing or invalid bearer token.
* `403 Forbidden`: caller does not have permission for the requested scope.
* `500 Internal Server Error`: unexpected server error while executing the query.