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

# Agent Metrics: Distribution Examples

> Distribution query examples for Gateway agent metrics API.

## Distribution queries

Aggregated snapshots of agent invocations 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-agent-metrics#quick-start).

<Note>
  Agent metrics include every Gateway request by default. Rows that didn't go through an agent will have `agentName`, `agentFramework`, and `agentServerType` set to `null` and show up as null buckets in `groupBy` output. `IS_NULL` is **not** supported on these three fields; to scope to specific known agents, use `agentName IN [...]` or one of the `STRING_*` operators.
</Note>

<AccordionGroup>
  <Accordion title="Volume by framework">
    Counts grouped by agent framework, useful for capacity planning across `langgraph`, `crewai`, etc.:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "groupBy": ["agentFramework"]
    }
    ```
  </Accordion>

  <Accordion title="Failure rate per agent">
    Counts grouped by agent and outcome. Surfaces flaky agents:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "groupBy": ["agentName", "isFailure"]
    }
    ```
  </Accordion>

  <Accordion title="Latency percentiles by framework">
    p50, p90, and p99 latency grouped by framework:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "p50", "column": "latencyMs"},
            {"type": "p90", "column": "latencyMs"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["agentFramework"]
    }
    ```
  </Accordion>

  <Accordion title="HTTP status code distribution">
    Group by raw `httpStatusCode`; rows without one show up as `null` (rendered as "unknown" in dashboards):

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "groupBy": ["httpStatusCode"]
    }
    ```
  </Accordion>

  <Accordion title="Server-type and framework mix">
    Cross-tab of transport vs framework:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "groupBy": ["agentServerType", "agentFramework"]
    }
    ```
  </Accordion>

  <Accordion title="Failures only by agent">
    Restrict to failed invocations:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["agentName"],
        "filters": [
            {"fieldName": "isFailure", "operator": "EQUAL", "value": true}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Slow invocations">
    Volume of invocations slower than 30 seconds, grouped by agent:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "agentName"}
        ],
        "groupBy": ["agentName"],
        "filters": [
            {"fieldName": "latencyMs", "operator": "GREATER_THAN", "value": 30000}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Scope to a known set of agents">
    Use `agentName IN [...]` to restrict the query to specific agents you care about:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "agentMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["agentName"],
        "filters": [
            {"fieldName": "agentName", "operator": "IN", "value": ["support-bot", "research-agent"]}
        ]
    }
    ```
  </Accordion>
</AccordionGroup>