GET /v1/analytics/schema lists every metric you can query and what each one supports, so an agent can build a valid query on the first try.
Quickstart
Calls per day over the last week, and the average sentiment score:- Node
- Python
- CLI
- cURL
metric:read permission. A read-only key is enough: a query never changes anything.
What you can query
Read the schema first. It lists the project’s metrics by slug, each with its output type, its default aggregation and the aggregations it supports, plus every filter and breakdown type and the custom call properties seen in the project.Measures
A query has one to ten measures: the things to aggregate.
Set
aggregation to choose another: AVG, MIN, MAX, SUM, MEDIAN, PERCENTILE (with percentile, e.g. 95), COUNT or PASS_RATE. The schema lists which ones each metric supports, and a query asking for one it doesn’t support returns 400 saying which to use instead.
- Per call first. Metric values are folded to one value per call before they are aggregated (
distinctBy: CALL), so a long call with many scored segments doesn’t outweigh a short one. SetdistinctBy: NONEto aggregate every value. - Pass rates.
PASS_RATEis the share of calls that meet a condition, from 0 to 1:{ "metric": "response_time", "aggregation": "PASS_RATE", "passOperator": "LESS_THAN", "passValue": 800 }. A threshold metric already carries its condition, so querying it by slug gives its pass rate directly.sampleSizeis the number of calls evaluated;0means no data, not 0%. - Units. Values come back in the metric’s display units.
Time windows
timeRange picks the window. It defaults to the last 30 days, and covers at most two years.
timezone (an IANA name such as America/New_York, default UTC) decides where days, weeks and calendar periods start. interval (HOUR, DAY, WEEK, MONTH) sets the bucket size; leave it out and it is chosen from the window’s length. A window that would produce more than 500 buckets steps to a coarser interval. Set includeBuckets: false to get totals only.
Filters, breakdowns and comparisons
Filters narrow what is counted. Top-levelfilters apply to every measure; a measure’s own filters add to them.
operator defaults to EQUALS; the others are NOT_EQUALS, GREATER_THAN, GREATER_THAN_OR_EQUAL_TO, LESS_THAN, LESS_THAN_OR_EQUAL_TO, CONTAINS, STARTS_WITH, IS_SET and IS_NOT_SET. The schema lists every filter type and the properties each accepts.
Set or missing. IS_SET and IS_NOT_SET apply to CALL_PROPERTY filters only and take no value. IS_SET keeps conversations that have the property, whatever its value (an empty string included); IS_NOT_SET keeps the ones missing it: never sent, sent as null, or removed. A property no conversation has carried is missing on all of them.
value with them, using them on another filter type, or using them as a PASS_RATE passOperator returns 400. On the system properties, direction and is_simulated are set on every call and on no chat, and duration_seconds is set on calls that lasted more than zero seconds; ended_reason doesn’t support them.
Breakdowns split a measure into one series per value. { "metric": "sentiment_score", "breakdown": { "type": "AGENT_PROPERTY" } } returns sentiment per agent; { "type": "CALL_PROPERTY", "property": "direction" } splits by inbound and outbound. The 50 largest series are returned, and omittedSeries counts the rest.
Comparisons:
comparisonMode: "PREVIOUS_PERIOD"adds the preceding window of the same length to every series (comparisonValue, and per bucket).comparisonGroupsruns every measure once per named filter set, for example one group per agent or per region (2 to 5 groups). While groups are set, breakdowns are ignored: each group is one series.
Filter by another metric
AMETRIC_VALUE filter keeps the conversations where a different metric’s value matches: for example, the pass rate of retrieved_accurately only over the calls where information_given is true. It works as a top-level filter, on a measure, in a comparison group and as a dashboard-level filter.
propertyis the filter metric’s id, asGET /v1/analytics/schemalists it. A slug is not accepted here (unlike a measure’smetric), and returns400.- One side. Add
.AGENTor.CUSTOMERto read only that participant’s value of a per-participant metric:"<metric-id>.AGENT". Without it, either side’s value can match. valueis required. A conversation matches on its latest value for the filter metric; conversations it hasn’t scored are left out.
On a threshold,
PASSED keeps the conversations that passed it and FAILED the ones that failed it, each evaluated the same way as the threshold’s own pass rate. NOT_EQUALS flips the status, so NOT_EQUALS PASSED is the same as EQUALS FAILED. A conversation with no values for the metric the threshold checks is in neither set. A threshold takes no .AGENT or .CUSTOMER suffix: it reads the side it was defined on.
STARTS_WITH is never supported. The query returns 400, naming the problem, when:
propertyisn’t a metric id, optionally followed by.AGENTor.CUSTOMER- the metric doesn’t exist in your organization
valueis missing or empty, or isn’t a number for a number-type metric ortrue/falsefor a boolean- the operator isn’t one the metric’s output type supports, or a threshold’s
valueisn’tPASSEDorFAILED
The response
measureIndex points back to the measure in your request. value is the aggregate over the whole window, and buckets holds the per-interval values.
A query the analytics store can’t answer returns 400 naming the part it can’t, never unfiltered numbers. An unknown metric slug returns 404.
From a query to a dashboard
A dashboard widget is a query plus a name, a chart type and a size. Once a query answers the question, save it as a widget withPOST /v1/dashboard/{dashboardId}/widget, or declare the dashboard in config as code.
Dashboards
Save queries as widgets and read them back over the API
Dashboards as code
Define dashboards in YAML next to the rest of your config