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

# Routing Metrics: Filtering

> Filter operators, fields, and patterns for Gateway routing metrics API queries

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

### Filter object structure

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

    ```json theme={"dark"}
    {
        "fieldName": "requestedModel",
        "operator": "IN",
        "value": ["gpt-4"]
    }
    ```
  </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>

### Filterable fields

<Note>
  `httpStatusCode`, `errorType`, and `latencyMs` are **not** filterable on `configMetrics`. Sending them returns `400 Bad Request` with `Unsupported gateway config filter name: <field>`. Use `status` in `groupBy` to see allowed vs blocked or failure outcomes instead.
</Note>

| Field                            | Type   | Allowed operators                       |
| -------------------------------- | ------ | --------------------------------------- |
| `loadbalanceRuleId`              | string | `IN`, `NOT_IN`                          |
| `ratelimitRuleId`                | string | `IN`, `NOT_IN`                          |
| `budgetRuleId`                   | string | `IN`, `NOT_IN`                          |
| `requestedModel`                 | string | `IN`, `NOT_IN`                          |
| `targetModel`                    | string | `IN`, `NOT_IN`                          |
| `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`       |
| `conversationID`                 | string | full string operator set (no `IS_NULL`) |
| `metadataKey` / `metadata.<key>` | string | full string operator set (no `IS_NULL`) |

### Filter operators

#### 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 | `["gpt-4", "gpt-3.5-turbo"]` |
| `NOT_IN`                 | Exclude values in the list  | `["deprecated-model"]`       |
| `STRING_CONTAINS`        | Contains substring          | `"prod"`                     |
| `STRING_NOT_CONTAINS`    | Does not contain substring  | `"staging"`                  |
| `STRING_STARTS_WITH`     | Starts with prefix          | `"prod-"`                    |
| `STRING_NOT_STARTS_WITH` | Does not start with prefix  | `"internal-"`                |
| `STRING_ENDS_WITH`       | Ends with suffix            | `"-v1"`                      |
| `STRING_NOT_ENDS_WITH`   | Does not end with suffix    | `"-deprecated"`              |

#### 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](#string-field-operators) table.

### 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": "configMetrics",
    "type": "distribution",
    "filters": [
        {"fieldName": "requestedModel", "operator": "IN", "value": ["gpt-4"]},
        {"fieldName": "loadbalanceRuleId", "operator": "IN", "value": ["<rule-id>"]},
        {"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
    ],
    "groupBy": ["targetModel", "status"]
}
```