Run an analytics query
Aggregates metric values and conversation counts over a time window and returns one series per measure, with a total for the window and per-interval buckets. The same query a dashboard widget runs, without saving anything.
measures: what to aggregate. A METRIC measure names its metric by slug; CONVERSATION counts conversations; UPTIME reads health checks. The aggregation defaults by the metric’s output type.timeRange: LAST n DAYS/WEEKS/MONTHS, a CALENDAR_ALIGNED period (TODAY, THIS_MONTH, …), FIXED from/to, or SINCE. Defaults to the last 30 days; at most 731 days. Calendar periods and buckets align totimezone(IANA, default UTC).filtersapply to every measure; a measure’s ownfiltersadd to them.breakdownon a measure returns one series per value (largest 50 kept).comparisonGroups(2 to 5) run every measure once per named filter set;comparisonMode: PREVIOUS_PERIODadds the preceding window’s values.
Values are in the metric’s display units. A PASS_RATE is a 0 to 1 share; sampleSize 0 means no data.
A query the analytics store cannot answer returns 400 naming the unsupported part.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
An aggregate query: one or more measures over a time window, optionally filtered, broken down and compared. GET /v1/analytics/schema lists the metrics, filters and breakdowns available.
What to aggregate: 1 to 10 measures.
1 - 10 elementsApplied to every measure, on top of each measure's own filters.
20Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets.
HOUR, DAY, WEEK, MONTH PREVIOUS_PERIOD adds the preceding window of the same length to every series.
NONE, PREVIOUS_PERIOD Run every measure once per named filter set, e.g. one group per agent.
2 - 5 elementsDefaults to the last 30 days.
- Option 1
- Option 2
- Option 3
- Option 4
IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC.
1Set false to return only the window totals.
Response
The query result
One series per measure (or per breakdown value / comparison group). value is the aggregate over the whole window; buckets hold the per-interval values.