---
title: "Run an analytics query"
method: POST
path: "/api/v1/analytics/query"
---

# Run an analytics query

`POST /api/v1/analytics/query`

Runs a query against a versioned analytics catalog model and returns a columnar table. Totals queries (no dimensions) return exactly one row. Grouped, dimension-ordered queries may paginate with an opaque `cursor`.

## Headers

- `x-request-id` string

## Request body

- AnalyticsQueryRequest
  - `model` 'agent_runs' | 'agent_user_activity', required — Catalog model name. The current catalog supports `agent_runs` and `agent_user_activity`.
  - `metrics` string[], required — Unique catalog metric names to select.
  - `dimensions` string[] — Unique catalog dimensions to group by.
  - `filters` QueryFilter[] — Dimension filters: `eq` with one `value`, or `in` with 1–50 `values`.
    - union
      - object
        - `member` string, required
        - `op` 'eq', required
        - `value` string, required
      - object
        - `member` string, required
        - `op` 'in', required
        - `values` string[], required
  - `range` QueryRange, required
    - `start` string, date, required — Inclusive, valid calendar date (`YYYY-MM-DD`) in the requested timezone. Must be on or before `end`.
    - `end` string, date, required — Inclusive, valid calendar date (`YYYY-MM-DD`). The range may cover at most 366 days.
    - `timezone` string, required — Canonical IANA timezone identifier, for example `America/Chicago` or `UTC`. Numeric offsets and legacy aliases are rejected.
  - `order` QueryOrderTerm[] — Up to eight unique order terms. Members must be selected metrics or dimensions. Totals queries cannot specify order terms.
    - `member` string, required — A selected metric or dimension name.
    - `direction` 'asc' | 'desc', required
  - `limit` integer — Maximum rows returned per page.
  - `cursor` string — Opaque continuation cursor from a previous grouped response. Not accepted on totals or metric-ordered queries.

## Response `200`

Columnar query results.

- AnalyticsQueryResponse
  - `queryId` string, uuid, required — Unique identifier for this execution.
  - `catalogVersion` string, required — Catalog version used to produce this response.
  - `asOf` string, date-time, required — Inclusion boundary used for this response and any cursor continuation.
  - `range` object, required
    - `start` string, date, required
    - `end` string, date, required
    - `timezone` string, required
    - `startUtc` string, date-time, required — Inclusive UTC instant the range resolves to.
    - `endUtc` string, date-time, required — Exclusive UTC instant the range resolves to.
  - `columns` Column[], required — Ordered column descriptors; a selected dimension is followed by its companions, then metrics.
    - `name` string, required — Output column name.
    - `type` 'string' | 'number' | 'date', required — Value type of the column.
    - `member` string, required — Catalog member this column belongs to; companion columns share their dimension's member name.
  - `rows` array[], required — Values in the same order as `columns`.
    - union[]
      - union
        - string
        - number
        - unknown
  - `cursor` string, nullable, required — Continuation cursor for the next page, or `null` when there is no next page.
  - `warnings` Warning[], required — Non-fatal semantic notices.
    - `code` 'non_additive_metric', required
    - `member` string, required
    - `message` string, required

## Other responses

- `400` — Invalid request. `error.code` is one of `invalid_query`, `unknown_member`, `range_too_large`, or `invalid_cursor`.
- `401` — A missing or malformed key returns this response without spending an admission limit. A well-formed unknown or revoked key normally returns the same response, but can return 429 while the global credential-verification budget is exhausted.
- `403` — The key is valid but does not include `analytics:read`.
- `429` — A per-key rate limit, the global unknown-credential verification budget, or an analytics concurrency limit was exceeded. Read `Retry-After`.
- `500` — An unexpected application or infrastructure failure occurred.

---

[API](https://skmtc.dev/burthq/apis/burt-analytics-api.md) · [All operations](https://skmtc.dev/burthq/apis/burt-analytics-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/burthq/burt-analytics-api/revisions/fcb6a24b0e42/schema)