> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roark.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# roark analytics query

> 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 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.

```bash Synopsis theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark analytics query [options]
```

> [!NOTE]
>
> Calls `POST /v1/analytics/query`

## Options

**--measures** `array` *required*

What to aggregate: 1 to 10 measures.

**--filters** `array`

Applied to every measure, on top of each measure's own filters.

**--interval** `string`

Bucket size. Defaults from the window's length and steps coarser when the window would exceed 500 buckets. One of `HOUR`, `DAY`, `WEEK`, `MONTH`

**--comparison-mode** `string`

`PREVIOUS_PERIOD` adds the preceding window of the same length to every series. One of `NONE`, `PREVIOUS_PERIOD`

**--comparison-groups** `array`

Run every measure once per named filter set, e.g. one group per agent.

**--time-range** `string`

Defaults to the last 30 days.

**--timezone** `string`

IANA zone that buckets and calendar periods align to, e.g. America/New\_York. Defaults to UTC.

**--include-buckets** `switch`

Set false to return only the window totals.

## Example

```bash theme={"theme":{"light":"everforest-light","dark":"everforest-dark"}}
roark analytics query --measures <value>
```

Every command also takes the [global options](/cli-reference/overview.md#global-options) and sets one
of the [exit codes](/cli-reference/overview.md#exit-codes).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.