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, MCP, Cache, Routing, and Agent 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 <your_api_key> 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 for how these rules are defined and evaluated.

Authentication

Get your API key

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.

Quick start

Distribution query

Counts and latency percentiles per guardrail and outcome, restricted to input-scope evaluations:

import requests

response = requests.post(
    "https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query",
    headers={
        "Authorization": "Bearer <your_api_key>",
        "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:

import requests

response = requests.post(
    "https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query",
    headers={
        "Authorization": "Bearer <your_api_key>",
        "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 <your_api_key> and Content-Type: application/json.

Request parameters

startTs · string · required

ISO 8601 timestamp marking the inclusive lower bound of the query window.

endTs · string · required

ISO 8601 timestamp marking the exclusive upper bound of the query window.

datasource · string · required

The data source to query. Use "guardrailMetrics" for Gateway guardrail metrics.

type · string · required

The type of query to execute:

• "distribution": returns aggregated rows (one row per groupBy combination).
• "timeseries": returns time-bucketed rows. Requires interval.

aggregations · array

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

groupBy · array

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

filters · array

Array of filter objects, AND-combined. See Filtering below for the full operator reference and the per-field allow-list.

interval · string

Required for timeseries queries. Bucket size as <positive integer> <unit>, where <unit> 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.

intervalInSeconds · number · deprecated

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.

Field filters

For standard datasource fields, use fieldName:

{
    "fieldName": "guardrailName",
    "operator": "IN",
    "value": ["pii-detector", "toxicity-filter"]
}

Metadata filters

For custom request-metadata keys, use metadataKey. Works on every datasource:

{
    "metadataKey": "environment",
    "operator": "IN",
    "value": ["production"]
}

Filterable fields and allowed operators

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.<key>	string	full string operator set

Filter operators reference

String field operators

Operator	Description	Example value
EQUAL	Exact match	"[e-mail]"
NOT_EQUAL	Not equal to value	"[e-mail]"
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, team unnesting, and combining filters

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:

{
    "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.

Distribution examples

Pass/fail breakdown per guardrail

Counts grouped by guardrail and outcome, useful for spotting guardrails that fail most often:

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"]
}

Latency percentiles on output-scope guardrails

p50, p90, and p99 grouped by guardrail, restricted to output-scope evaluations:

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"]}
    ]
}

Slow guardrail evaluations

Volume and average latency of evaluations slower than 500 ms, grouped by guardrail:

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}
    ]
}

Failures only

Restrict to failed evaluations, grouped by guardrail and scope:

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"]}
    ]
}

Group by team and metadata environment

Counts by team and a custom metadata key, restricted via team array filter:

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"]}
    ]
}

Distinct guardrails per scope

How many unique guardrails ran on input vs output:

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"]
}

Restrict to specific guardrails

Use IN on guardrailName to focus on a subset:

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 <positive integer> <unit> strings like "5 minute", "1 hour", or "1 day".

Hourly evaluation volume

Total guardrail evaluations per hour:

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"}
    ]
}

Hourly p99 latency by scope

Track p99 evaluation latency per scope (input / output) bucket-by-bucket:

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"]
}

Hourly failures per guardrail

Track per-guardrail failure rate over time:

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"]}
    ]
}

5-minute traffic during incident

Fine-grained breakdown to investigate a regression:

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 evaluations over a week

Daily evaluation volume per guardrail across a 7-day window:

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"]
}

Hourly p99 latency for specific guardrails

Focus on a few guardrails of interest:

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"]}
    ]
}

Hourly volume by team

Per-team guardrail activity over time:

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:

{
  "data": {
    "dataPoints": [
      {
        "startTimestamp": "2026-04-29T12:00:00.000Z",
        "endTimestamp": "2026-04-29T13:00:00.000Z",
        "total": 1234,
        "<aggregationKey>": 0,
        "<groupByKey>": "value-or-null"
      }
    ]
  }
}

• total: implicit COUNT(*) for the row. Always present.
• <aggregationKey>: one key per requested aggregation. The key is <type><Column> in camelCase (e.g. countGuardrailName, p99LatencyMs).
• <groupByKey>: 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.

Distribution response example

{
  "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
      }
    ]
  }
}

Timeseries response example

{
  "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:

{
  "statusCode": 400,
  "message": "Invalid query",
  "details": ["..."]
}

Common causes and other status codes

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.