Skip to main content
The analytics API returns the numbers behind your dashboards without opening the dashboard: average sentiment this week, calls per day, task completion by agent, a pass rate against last month. Send a query, get back a total and a per-interval series for each thing you asked about. Nothing is saved; to keep a query, add it to a dashboard as a widget. It is built for code and for AI agents alike. 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:
The key needs the 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.
The MCP server exposes the same two operations, so an assistant connected to Roark can read the schema and run queries on its own.

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. Set distinctBy: NONE to aggregate every value.
  • Pass rates. PASS_RATE is 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. sampleSize is the number of calls evaluated; 0 means 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-level filters 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.
Sending a 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).
  • comparisonGroups runs 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

A METRIC_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.
  • property is the filter metric’s id, as GET /v1/analytics/schema lists it. A slug is not accepted here (unlike a measure’s metric), and returns 400.
  • One side. Add .AGENT or .CUSTOMER to read only that participant’s value of a per-participant metric: "<metric-id>.AGENT". Without it, either side’s value can match.
  • value is required. A conversation matches on its latest value for the filter metric; conversations it hasn’t scored are left out.
The operators follow the filter metric’s output type: 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:
  • property isn’t a metric id, optionally followed by .AGENT or .CUSTOMER
  • the metric doesn’t exist in your organization
  • value is missing or empty, or isn’t a number for a number-type metric or true / false for a boolean
  • the operator isn’t one the metric’s output type supports, or a threshold’s value isn’t PASSED or FAILED
A widget with one of these in its own filters or comparison groups is refused when you save it, rather than failing on every read.

The response

There is one series per measure, or per breakdown value or comparison group. 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 with POST /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