> ## 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: Distribution Examples

> Distribution query examples for Gateway guardrail metrics API

## Distribution queries

Aggregated snapshots of guardrail evaluations over a time window. Every example below posts JSON to:

```
POST https://{your_control_plane_url}/api/svc/v1/llm-gateway/metrics/query
```

with `Authorization: Bearer <your_api_key>` and `Content-Type: application/json`. To keep the snippets short, only the JSON body is shown; the wrapper is identical to the [Overview Quick Start](/docs/ai-gateway/fetch-guardrail-metrics#quick-start).

<AccordionGroup>
  <Accordion title="Pass/fail breakdown per guardrail">
    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"]
    }
    ```
  </Accordion>

  <Accordion title="Latency percentiles on output-scope guardrails">
    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"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Slow guardrail evaluations">
    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}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Failures only">
    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"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Group by team and metadata environment">
    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"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Distinct guardrails per scope">
    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"]
    }
    ```
  </Accordion>

  <Accordion title="Restrict to specific guardrails">
    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"]}
        ]
    }
    ```
  </Accordion>
</AccordionGroup>