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

# MCP Metrics

> Query Gateway MCP server and tool metrics for traffic and latency analytics via API.

The **Gateway MCP Metrics Query API** provides a flexible way to query Gateway MCP server and tool metrics: methods invoked, tools called, latency, errors, and traffic mix. You can retrieve either **distribution** (aggregated) or **timeseries** results with powerful filtering and grouping.

<Info>
  This page covers `datasource: "mcpMetrics"`. For other datasources, see [Model](/docs/ai-gateway/fetch-model-metrics), [Guardrail](/docs/ai-gateway/fetch-guardrail-metrics), [Cache](/docs/ai-gateway/fetch-cache-metrics), [Routing](/docs/ai-gateway/fetch-routing-metrics), and [Agent](/docs/ai-gateway/fetch-agent-metrics) metrics.
</Info>

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](/docs/ai-gateway/data-access) for how these rules are defined and evaluated.

## Authentication

<Accordion title="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](/docs/ai-gateway/authentication).
</Accordion>

## Quick start

<Warning>
  By default, the API returns metrics across **all MCP methods** including non-tool calls (`initialize`, `tools/list`, `prompts/list`, etc.). To analyse tool-call usage specifically, filter with `{"fieldName": "method", "operator": "IN", "value": ["tools/call"]}` and optionally group by `toolName`.
</Warning>

<Note>
  Token, cost, and time-to-first-token aggregations (`inputTokens`, `outputTokens`, `costInUSD`, `timeToFirstTokenMs`, `interTokenLatencyMs`, `timePerOutputTokenLatencyMs`) **do not apply** to MCP metrics; they are model-only signals. Use the [Model Metrics](/docs/ai-gateway/fetch-model-metrics) datasource if you need them.
</Note>

<Tabs>
  <Tab title="Distribution query">
    Top MCP servers by request count and p99 latency:

    ```python theme={"dark"}
    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": "mcpMetrics",
            "type": "distribution",
            "aggregations": [
                {"type": "count", "column": "mcpServerName"},
                {"type": "avg", "column": "latencyMs"},
                {"type": "p99", "column": "latencyMs"}
            ],
            "groupBy": ["mcpServerName"]
        }
    )

    print(response.json())
    ```
  </Tab>

  <Tab title="Timeseries query">
    Hourly tool-call counts and p99 latency by tool:

    ```python theme={"dark"}
    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": "mcpMetrics",
            "type": "timeseries",
            "interval": "1 hour",
            "aggregations": [
                {"type": "count", "column": "toolName"},
                {"type": "p99", "column": "latencyMs"}
            ],
            "groupBy": ["toolName"],
            "filters": [
                {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
            ]
        }
    )

    print(response.json())
    ```
  </Tab>
</Tabs>

## API reference

Post JSON to the endpoint above with `Authorization: Bearer <your_api_key>` and `Content-Type: application/json`.

### Request parameters

<ParamField path="startTs" type="string" required>
  ISO 8601 timestamp marking the **inclusive** lower bound of the query window (e.g. `"2026-04-21T00:00:00.000Z"`).
</ParamField>

<ParamField path="endTs" type="string" required>
  ISO 8601 timestamp marking the **exclusive** upper bound of the query window (e.g. `"2026-04-22T00:00:00.000Z"`).
</ParamField>

<ParamField path="datasource" type="string" required>
  The data source to query. Use `"mcpMetrics"` for Gateway MCP metrics.
</ParamField>

<ParamField path="type" type="string" required>
  The type of query to execute:

  * `"distribution"`: returns aggregated rows (one row per `groupBy` combination).
  * `"timeseries"`: returns time-bucketed rows (one row per bucket per `groupBy` combination). Requires `interval`.
</ParamField>

<ParamField path="aggregations" type="array">
  Array of `{ type, column }` objects describing the aggregations to compute. When omitted, only the implicit `total = COUNT(*)` is returned.

  ```json theme={"dark"}
  "aggregations": [
      {"type": "count", "column": "mcpServerName"},
      {"type": "avg", "column": "latencyMs"},
      {"type": "p99", "column": "latencyMs"}
  ]
  ```

  <Accordion title="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`                                                     | `sum` normalised by the interval in seconds (timeseries only) |
    | `rateAvg`                                                     | `avg` normalised by the interval in seconds (timeseries only) |
    | `rateMin`                                                     | `min` normalised by the interval in seconds (timeseries only) |
    | `rateMax`                                                     | `max` normalised by the interval in seconds (timeseries only) |
    | `ratePerMinute`                                               | Value divided by the interval in minutes (timeseries only)    |
  </Accordion>

  <Accordion title="Supported aggregation columns">
    | Column          | Supported aggregation types    | Notes                                           |
    | --------------- | ------------------------------ | ----------------------------------------------- |
    | `latencyMs`     | all scalar and all percentiles | Total MCP request latency in ms                 |
    | `mcpServerName` | `count`, `countDistinct`       | Useful for "how many servers were called?"      |
    | `method`        | `count`, `countDistinct`       | Useful for traffic-mix breakdowns               |
    | `toolName`      | `count`, `countDistinct`       | Useful when filtered to `method = "tools/call"` |
  </Accordion>
</ParamField>

<ParamField path="groupBy" type="array">
  Array of field names to group results by. Custom metadata keys are supported with a `metadata.` prefix (e.g. `"metadata.environment"`).

  ```json theme={"dark"}
  "groupBy": ["mcpServerName", "toolName", "metadata.environment"]
  ```

  <Accordion title="Available group-by fields">
    | Field                  | Notes                                                                   |
    | ---------------------- | ----------------------------------------------------------------------- |
    | `mcpServerName`        | The MCP server name                                                     |
    | `method`               | JSON-RPC method invoked (e.g. `tools/call`, `tools/list`, `initialize`) |
    | `toolName`             | Tool invoked (populated only for `tools/call`)                          |
    | `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.
  </Accordion>
</ParamField>

<ParamField path="filters" type="array">
  Array of filter objects, AND-combined. See [Filtering](#filtering) below for the full operator reference and the per-field allow-list.
</ParamField>

<ParamField path="interval" type="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.
</ParamField>

<ParamField path="intervalInSeconds" type="number" deprecated>
  **Deprecated alias for `interval`.** Accepts a positive integer number of seconds (e.g. `3600` for hourly). Prefer `interval` in new code. If both are provided, `interval` wins.
</ParamField>

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

<Tabs>
  <Tab title="Field filters">
    For standard datasource fields, use `fieldName`:

    ```json theme={"dark"}
    {
        "fieldName": "method",
        "operator": "IN",
        "value": ["tools/call"]
    }
    ```
  </Tab>

  <Tab title="Metadata filters">
    For custom request-metadata keys, use `metadataKey`. Works on every datasource:

    ```json theme={"dark"}
    {
        "metadataKey": "environment",
        "operator": "IN",
        "value": ["production"]
    }
    ```
  </Tab>
</Tabs>

<Accordion title="Filterable fields and allowed operators">
  The MCP-specific string fields (`mcpServerName`, `method`, `toolName`) 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 `userEmail`, `virtualAccount`, and `conversationID`.

  | Field                            | Type   | Allowed operators                                                               |
  | -------------------------------- | ------ | ------------------------------------------------------------------------------- |
  | `mcpServerName`                  | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
  | `method`                         | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
  | `toolName`                       | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`     |
  | `userEmail`                      | string | full string operator set                                                        |
  | `virtualAccount`                 | string | full string operator set                                                        |
  | `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                                                        |
</Accordion>

<Accordion title="Filter operators reference">
  **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                                                        | `["tools/call", "tools/list"]` |
  | `NOT_IN`                 | Exclude values in the list                                                         | `["initialize"]`               |
  | `STRING_CONTAINS`        | Contains substring                                                                 | `"github"`                     |
  | `STRING_NOT_CONTAINS`    | Does not contain substring                                                         | `"internal"`                   |
  | `STRING_STARTS_WITH`     | Starts with prefix                                                                 | `"github-"`                    |
  | `STRING_NOT_STARTS_WITH` | Does not start with prefix                                                         | `"internal-"`                  |
  | `STRING_ENDS_WITH`       | Ends with suffix                                                                   | `"-mcp"`                       |
  | `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"]`           |
</Accordion>

<Accordion title="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 (string literal, prefix is `metadata.`).

  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": "mcpMetrics",
      "type": "distribution",
      "filters": [
          {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
          {"fieldName": "mcpServerName", "operator": "IN", "value": ["github-mcp", "atlassian-mcp"]},
          {"fieldName": "latencyMs", "operator": "BETWEEN", "value": [100, 10000]},
          {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
      ],
      "groupBy": ["mcpServerName", "toolName"]
  }
  ```
</Accordion>

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

<Note>
  MCP metrics include **all JSON-RPC methods** by default. Many of the examples below pin the tool-call subset with `{"fieldName": "method", "operator": "IN", "value": ["tools/call"]}` so `toolName` is populated.
</Note>

### Distribution examples

<AccordionGroup>
  <Accordion title="Top servers by request count">
    Count requests per server, alongside p99 latency:

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

  <Accordion title="Tool calls grouped by tool name">
    Restrict to `tools/call` and group by `toolName`:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Method distribution per server">
    Traffic mix per server (initialize / tools/list / tools/call / ...):

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

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

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "p50", "column": "latencyMs"},
            {"type": "p90", "column": "latencyMs"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Distinct tools per server">
    How many unique tools each server exposed:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "countDistinct", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Exclude internal tools">
    Count tool calls excluding internal/debug tools using `NOT_IN`:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "toolName", "operator": "NOT_IN", "value": ["internal-debug", "healthcheck", "echo"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="High-latency tool calls">
    Find slow tool calls (above 5 seconds):

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName", "toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "latencyMs", "operator": "GREATER_THAN", "value": 5000}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Group by metadata">
    Tool-call counts per metadata key:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName", "metadata.environment"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Filter by team">
    Tool-call activity scoped to a team:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["mcpServerName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Complex filter combination">
    Tool-call traffic on a known list of servers, latency window, scoped to a team:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "distribution",
        "aggregations": [
            {"type": "count", "column": "toolName"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["mcpServerName", "toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "mcpServerName", "operator": "IN", "value": ["github-mcp", "atlassian-mcp"]},
            {"fieldName": "latencyMs", "operator": "BETWEEN", "value": [100, 10000]},
            {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
        ]
    }
    ```
  </Accordion>
</AccordionGroup>

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

<AccordionGroup>
  <Accordion title="Hourly request volume">
    Total MCP requests per hour:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "count", "column": "mcpServerName"}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Hourly tool-call counts">
    Hourly tool calls grouped by tool:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Hourly p99 latency by server">
    Track regressions per server, bucket-by-bucket:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["mcpServerName"]
    }
    ```
  </Accordion>

  <Accordion title="Hourly method mix">
    Volume per JSON-RPC method over time:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "count", "column": "method"}
        ],
        "groupBy": ["method"]
    }
    ```
  </Accordion>

  <Accordion title="5-minute traffic on a specific server">
    Fine-grained tool-call traffic on one server:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-21T06:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "5 minute",
        "aggregations": [
            {"type": "count", "column": "toolName"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "mcpServerName", "operator": "IN", "value": ["github-mcp"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Daily traffic over a week">
    Daily tool-call volume across a 7-day window:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-14T00:00:00.000Z",
        "endTs": "2026-04-21T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 day",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Hourly counts by team">
    Per-team tool-call usage over time:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "count", "column": "toolName"}
        ],
        "groupBy": ["team"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha", "team-beta"]}
        ]
    }
    ```
  </Accordion>

  <Accordion title="Complex timeseries query">
    Multiple filters and grouping together:

    ```python theme={"dark"}
    json={
        "startTs": "2026-04-21T00:00:00.000Z",
        "endTs": "2026-04-22T00:00:00.000Z",
        "datasource": "mcpMetrics",
        "type": "timeseries",
        "interval": "1 hour",
        "aggregations": [
            {"type": "count", "column": "toolName"},
            {"type": "p99", "column": "latencyMs"}
        ],
        "groupBy": ["mcpServerName", "toolName"],
        "filters": [
            {"fieldName": "method", "operator": "IN", "value": ["tools/call"]},
            {"fieldName": "mcpServerName", "operator": "IN", "value": ["github-mcp", "atlassian-mcp"]},
            {"metadataKey": "environment", "operator": "IN", "value": ["production"]}
        ]
    }
    ```
  </Accordion>
</AccordionGroup>

## 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,
        "<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. `countToolName`, `p99LatencyMs`, `countDistinctMcpServerName`).
* **`<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`** / **`endTimestamp`**: present only for timeseries responses. Bucket start and end as ISO 8601 timestamp strings; `endTimestamp` equals the next bucket's `startTimestamp`. Distribution responses omit both.

<AccordionGroup>
  <Accordion title="Distribution response example">
    ```json theme={"dark"}
    {
      "data": {
        "dataPoints": [
          {
            "mcpServerName": "github-mcp",
            "total": 4200,
            "countMcpServerName": 4200,
            "avgLatencyMs": 142.3,
            "p99LatencyMs": 612.0
          },
          {
            "mcpServerName": "atlassian-mcp",
            "total": 1850,
            "countMcpServerName": 1850,
            "avgLatencyMs": 98.7,
            "p99LatencyMs": 411.5
          }
        ]
      }
    }
    ```
  </Accordion>

  <Accordion title="Timeseries response example">
    ```json theme={"dark"}
    {
      "data": {
        "dataPoints": [
          {
            "startTimestamp": "2026-04-21T00:00:00.000Z",
            "endTimestamp": "2026-04-21T01:00:00.000Z",
            "toolName": "create_issue",
            "total": 18,
            "countToolName": 18,
            "p99LatencyMs": 380.0
          },
          {
            "startTimestamp": "2026-04-21T01:00:00.000Z",
            "endTimestamp": "2026-04-21T02:00:00.000Z",
            "toolName": "create_issue",
            "total": 22,
            "countToolName": 22,
            "p99LatencyMs": 410.0
          }
        ]
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<Info>
  If `groupBy` is empty or omitted, the response collapses to a single row (or one row per timeseries bucket) summarising every MCP request inside the window.
</Info>

<Note>
  `toolName` rows are populated only for `method = "tools/call"`; rows for other methods will surface `toolName: null` in the response when grouped by it.
</Note>

### Error responses

A malformed query returns `400 Bad Request`:

```json theme={"dark"}
{
  "statusCode": 400,
  "message": "Invalid query",
  "details": ["..."]
}
```

<Accordion title="Common causes and other status codes">
  Common causes of `400`:

  * Operator not allowed on this field, for example, `EQUAL` on `mcpServerName` (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 (e.g. `inputTokens` on `mcpMetrics`).
  * 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.
</Accordion>