Metrics over time: event counts, unique users or sessions, the sum, average or p95 of a numeric property, optionally split by a property (one breakdown for every series, or each series by its own) and compared to the previous period. The workhorse for "how many / how much / is it growing" questions. interval "total" returns one de-duplicated number per series for the whole window.
View input schema
{
"type": "object",
"properties": {
"project": {
"type": "string",
"description": "Project handle (as in list_projects) or id. Optional when this connection is limited to one project or the workspace has only one.",
"maxLength": 128
},
"projects": {
"type": "array",
"items": {
"type": "string",
"maxLength": 128
},
"maxItems": 50,
"description": "Project handles (as in list_projects) or ids, to read across several apps. Leave out for every project this connection can reach. For one project use `project`; never pass both."
},
"series": {
"type": "array",
"minItems": 1,
"maxItems": 5,
"description": "One to five metrics. Each: {event, aggregation, property?, filters?, label?, breakdown?}. `property` is required for sum, avg and p95.",
"items": {
"type": "object",
"properties": {
"event": {
"type": "string",
"description": "Event name; omit for all events.",
"maxLength": 200
},
"aggregation": {
"type": "string",
"enum": [
"total",
"unique_users",
"unique_sessions",
"sum",
"avg",
"p95"
]
},
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"filters": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 0
}
},
"required": [
"combinator"
],
"additionalProperties": false
}
}
},
"required": [
"combinator"
],
"additionalProperties": false
}
}
},
"required": [
"combinator"
],
"additionalProperties": false
},
"label": {
"type": "string",
"maxLength": 100
},
"breakdown": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
}
},
"required": [
"aggregation"
],
"additionalProperties": false
}
},
"breakdowns": {
"type": "array",
"maxItems": 1,
"items": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"description": "Split every series without its own `breakdown` by one property."
},
"filters": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 20,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 5,
"items": {
"type": "object",
"description": "Filters combined with AND/OR: {combinator: \"AND\", filters: [{property: {scope, key}, op, values: [..]}], groups: [nested groups]}. Ops: eq, neq, in, contains, gt, lt, is_set. Values are strings.",
"properties": {
"combinator": {
"type": "string",
"enum": [
"AND",
"OR"
]
},
"filters": {
"type": "array",
"maxItems": 10,
"items": {
"type": "object",
"properties": {
"property": {
"type": "object",
"description": "{scope, key}. scope \"event\" = payload property, \"context\" = built-in dimension (country, browser, page_path, utm_source…), \"session\", \"user\" = user trait.",
"properties": {
"scope": {
"type": "string",
"enum": [
"event",
"context",
"session",
"user"
]
},
"key": {
"type": "string",
"maxLength": 1000
}
},
"required": [
"scope",
"key"
],
"additionalProperties": false
},
"op": {
"type": "string",
"enum": [
"eq",
"neq",
"in",
"contains",
"gt",
"lt",
"is_set"
]
},
"values": {
"type": "array",
"maxItems": 100,
"items": {
"type": "string",
"maxLength": 1000
}
}
},
"required": [
"property",
"op"
],
"additionalProperties": false
}
},
"groups": {
"type": "array",
"maxItems": 0
}
},
"required": [
"combinator"
],
"additionalProperties": false
}
}
},
"required": [
"combinator"
],
"additionalProperties": false
}
}
},
"required": [
"combinator"
],
"additionalProperties": false
},
"interval": {
"type": "string",
"enum": [
"hour",
"day",
"week",
"month",
"total"
],
"description": "Bucket size. Default chosen from the window (hour ≤2d, day ≤120d, week beyond)."
},
"compare": {
"type": "boolean",
"description": "Also compute the previous period of equal length."
},
"last": {
"type": "string",
"description": "Relative window ending now, e.g. \"1h\", \"24h\", \"7d\", \"30d\", \"90d\". Default \"14d\". Ignored when `from` is given.",
"pattern": "^\\d{1,4}[hdw]$"
},
"from": {
"type": "string",
"description": "Window start, ISO 8601 (e.g. \"2026-09-01\" or \"2026-09-01T12:00:00Z\")."
},
"to": {
"type": "string",
"description": "Window end, ISO 8601. Default now."
}
},
"required": [
"series"
],
"additionalProperties": false
}