> ## 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: Filtering
> Filter operators, fields, and patterns for Gateway agent 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
For standard datasource fields, use `fieldName`:
```json theme={"dark"}
{
"fieldName": "agentName",
"operator": "IN",
"value": ["support-bot", "research-agent"]
}
```
For custom request-metadata keys, use `metadataKey`. Works on every datasource:
```json theme={"dark"}
{
"metadataKey": "environment",
"operator": "IN",
"value": ["production"]
}
```
### Filterable fields
The agent-specific string fields (`agentName`, `agentFramework`, `agentServerType`) accept the narrow set `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH`. `IS_NULL` is **not** supported on these fields; sending it returns `400 Bad Request` with `Field "agentName" does not support operator "IS_NULL"`. `EQUAL` and `NOT_EQUAL` are only supported on subject fields (`userEmail`, `virtualAccount`) and `conversationID`.
| Field | Type | Allowed operators |
| -------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `agentName` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `agentFramework` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `agentServerType` | string | `IN`, `NOT_IN`, `STRING_CONTAINS`, `STRING_STARTS_WITH`, `STRING_ENDS_WITH` |
| `isFailure` | boolean | `EQUAL` |
| `httpStatusCode` | number | `EQUAL`, `NOT_EQUAL`, `IN`, `NOT_IN`, `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_EQUAL`, `LESS_THAN_EQUAL`, `IS_NULL` |
| `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.` | string | full string operator set |
### 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 | `["langgraph", "crewai"]` |
| `NOT_IN` | Exclude values in the list | `["deprecated-framework"]` |
| `STRING_CONTAINS` | Contains substring | `"graph"` |
| `STRING_NOT_CONTAINS` | Does not contain substring | `"internal"` |
| `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"` |
| `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 | `200` |
| `NOT_EQUAL` | Not equal to value | `200` |
| `IN` | Match any value in the list | `[200, 404, 500]` |
| `NOT_IN` | Exclude values in the list | `[200]` |
| `GREATER_THAN` | Strictly greater than | `499` |
| `LESS_THAN` | Strictly less than | `300` |
| `GREATER_THAN_EQUAL` | Greater than or equal to | `400` |
| `LESS_THAN_EQUAL` | Less than or equal to | `299` |
| `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` |
#### Boolean field operators
| Operator | Description | Example value |
| -------- | ----------- | ------------- |
| `EQUAL` | Exact match | `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 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": "agentMetrics",
"type": "distribution",
"filters": [
{"fieldName": "agentFramework", "operator": "IN", "value": ["langgraph"]},
{"fieldName": "agentName", "operator": "IN", "value": ["support-bot", "research-agent"]},
{"fieldName": "latencyMs", "operator": "BETWEEN", "value": [100, 10000]},
{"fieldName": "team", "operator": "ARRAY_HAS_ANY", "value": ["team-alpha"]}
],
"groupBy": ["agentName", "isFailure"]
}
```