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
Field filters
Metadata filters
For standard datasource fields, use fieldName:{
"fieldName": "agentName",
"operator": "IN",
"value": ["support-bot", "research-agent"]
}
For custom request-metadata keys, use metadataKey. Works on every datasource:{
"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.<key> | 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"] |
- 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 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:
{
"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"]
}
