---
title: "Run an analytics query"
method: POST
path: "/v1/analytics/query"
tags: ["Analytics"]
---

# Run an analytics query

`POST /v1/analytics/query`

## Request

- Base URL: `https://api.roark.ai`
- URL: `https://api.roark.ai/v1/analytics/query`
- Auth: HTTP bearer

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 to `timezone` (IANA, default UTC).
- `filters` apply to every measure; a measure's own `filters` add to them.
- `breakdown` on a measure returns one series per value (largest 50 kept).
- `comparisonGroups` (2 to 5) run every measure once per named filter set;
  `comparisonMode: PREVIOUS_PERIOD` adds 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.

## Request body

- AnalyticsQuery: 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.
  - `measures` object[], required: What to aggregate: 1 to 10 measures.
    - `type` 'METRIC' | 'CONVERSATION' | 'UPTIME': METRIC (default): a metric's values. CONVERSATION: conversation counts. UPTIME: health-check outcomes.
    - `metric` string: The metric's slug (e.g. `task_completion`) or id. Required for METRIC.
    - `aggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': Defaults by output type: AVG for numeric metrics, COUNT (split by value) for classification and text, PASS_RATE for thresholds and uptime, COUNT for conversations.
    - `percentile` integer: Required with PERCENTILE, e.g. 95.
    - `distinctBy` 'NONE' | 'CALL': CALL (default for metrics) folds each conversation to one value first, so a long call does not outweigh a short one. NONE aggregates every value.
    - `nestedAggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE': How each conversation is folded when distinctBy is CALL. Defaults to SUM under SUM, else AVG.
    - `nestedAggregationPercentile` integer
    - `passOperator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': PASS_RATE condition operator. Omit for a threshold metric: its own condition is used.
    - `passValue` union: PASS_RATE condition value, e.g. 4 or "resolved".
      - string
      - number
      - boolean
    - `breakdown` object: Split the measure into one series per value of this dimension (the largest 50 are returned). Ignored while comparisonGroups are set: each group is then one series.
      - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'DATASET', required
      - `property` string: The property to split by. Required for CALL_PROPERTY and METRIC_PROPERTY.
    - `filters` object[]: Filters for this measure only, on top of the query's filters.
      - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type.
      - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
      - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
      - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
        - string
        - number
        - boolean
    - `isBaseline` boolean: Mark one measure as the baseline: every series also reports its value as a percentage of it.
    - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN': Chart color on a dashboard.
  - `filters` object[]: Applied to every measure, on top of each measure's own filters.
    - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type.
    - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
    - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
    - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
      - string
      - number
      - boolean
  - `interval` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH': Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets.
  - `comparisonMode` 'NONE' | 'PREVIOUS_PERIOD': PREVIOUS_PERIOD adds the preceding window of the same length to every series.
  - `comparisonGroups` object[]: Run every measure once per named filter set, e.g. one group per agent.
    - `name` string, required: The series label; unique within the query.
    - `filters` object[], required
      - `type` 'METRIC_PROPERTY' | 'CALL_PROPERTY' | 'AGENT_PROPERTY' | 'CALL_ID' | 'MODALITY' | 'DATASET' | 'METRIC_VALUE', required: What the filter narrows on. GET /v1/analytics/schema lists each type.
      - `property` string: The property to compare. Required for CALL_PROPERTY and METRIC_PROPERTY; may be omitted for AGENT_PROPERTY, DATASET, MODALITY and CALL_ID.
      - `operator` 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'GREATER_THAN_OR_EQUAL_TO' | 'LESS_THAN' | 'LESS_THAN_OR_EQUAL_TO' | 'CONTAINS' | 'STARTS_WITH' | 'IS_SET' | 'IS_NOT_SET': Defaults to EQUALS. IS_SET / IS_NOT_SET (CALL_PROPERTY only) keep conversations where the property is set, whatever the value, or missing (never sent, sent as null, or removed); they take no value.
      - `value` union: The value to compare against (an agent id, "call" / "chat", a property value). Required except with IS_SET / IS_NOT_SET.
        - string
        - number
        - boolean
    - `color` 'GREEN' | 'RED' | 'ORANGE' | 'PURPLE' | 'GREY' | 'BLUE' | 'PEACH' | 'TEAL' | 'INDIGO' | 'AMBER' | 'ROSE' | 'CYAN'
  - `timeRange` union: Defaults to the last 30 days.
    - object
      - `type` 'LAST', required
      - `value` integer, required
      - `unit` 'DAYS' | 'WEEKS' | 'MONTHS', required
    - object
      - `type` 'CALENDAR_ALIGNED', required
      - `period` 'TODAY' | 'YESTERDAY' | 'THIS_WEEK' | 'LAST_WEEK' | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_YEAR' | 'LAST_YEAR', required
    - object
      - `type` 'FIXED', required
      - `from` string, date-time, required
      - `to` string, date-time, required
    - object
      - `type` 'SINCE', required
      - `from` string, date-time, required
  - `timezone` string: IANA zone that buckets and calendar periods align to, e.g. America/New_York. Defaults to UTC.
  - `includeBuckets` boolean: Set false to return only the window totals.

## Response `200`

The query result

- object
  - `data` AnalyticsResult, required: One series per measure (or per breakdown value / comparison group). `value` is the aggregate over the whole window; `buckets` hold the per-interval values.
    - `from` string, required
    - `to` string, required
    - `interval` 'HOUR' | 'DAY' | 'WEEK' | 'MONTH', required
    - `timezone` string, required
    - `series` object[], required
      - `measureIndex` integer, required
      - `type` 'METRIC' | 'CONVERSATION' | 'UPTIME', required
      - `metric` string, nullable, required
      - `aggregation` 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'MEDIAN' | 'PERCENTILE' | 'PASS_RATE', required
      - `breakdownValue` string, nullable, required
      - `comparisonGroup` string, nullable, required
      - `value` number, required
      - `sampleSize` number, nullable, required
      - `comparisonValue` number, nullable, required
      - `percentageOfBaseline` number, nullable, required
      - `buckets` object[], required
        - `date` string, required
        - `value` number, required
        - `passed` number
        - `sampleSize` number
        - `comparisonDate` string
        - `comparisonValue` number
        - `percentageOfBaseline` number
    - `omittedSeries` integer, required

## Other responses

- `400`: Invalid or unsupported query
- `401`: Unauthorized
- `403`: Forbidden
- `404`: A metric was not found in this project
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

> 188 revisions in range; 1 not diffed.

- **2026-10-21** `8913d3b08c7b`: 11 info
  - the request property `comparisonGroups/items/filters/items/value` became optional
  - the request property `filters/items/value` became optional
  - the request property `measures/items/filters/items/value` became optional
  - added the new `IS_NOT_SET` enum value to the request property `comparisonGroups/items/filters/items/operator`
  - …7 more
- **2026-10-21** `2e403107d6ec`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/roarkhq/apis/roark-analytics-api/changes/v1/analytics/query/post.md)

---

[API](https://skmtc.dev/roarkhq/apis/roark-analytics-api.md) - [All operations](https://skmtc.dev/roarkhq/apis/roark-analytics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/roarkhq/apis/roark-analytics-api/revisions/efc3377249d1?raw)