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

# Run an ad-hoc analytics query

`POST /analytics/query`

Resolves the given view definition against the supplied variables and executes it.

## Request body

- AnalyticsQueryRequest
  - `definition` AnalyticsViewDefinition, required
    - `dimensions` string[]
    - `filters` AnalyticsFilter[]
      - `field` string
      - `op` 'eq' | 'contains' | 'not_contains' | 'gt' | 'lt' | 'gte' | 'in' | 'not_in' | 'before' | 'after'
      - `optional` boolean
      - `value` string[]
    - `limit` integer
    - `metrics` TypesMetric[], required
    - `shape` 'timeseries' | 'breakdown', required
    - `sort` AnalyticsSortSpec[]
      - `dir` 'asc' | 'desc'
      - `field` string
    - `time` AnalyticsTimeSpecRaw
      - `grain` 'hour' | 'day' | 'week' | 'month'
      - `range` string
    - `variables` AnalyticsVariable[]
      - `default` string[]
      - `name` string
      - `required` boolean
      - `type` 'date_range' | 'string' | 'string_list' | 'number' | 'enum' | 'boolean', required
  - `variables` object

## Response `200`

OK

- AnalyticsQueryResult
  - `columns` AnalyticsColumn[]
    - `currency` string
    - `name` string
    - `role` 'dimension' | 'metric'
    - `type` 'string' | 'decimal' | 'datetime'
  - `meta` AnalyticsQueryMeta
    - `query_source` string
  - `rows` array[]
    - string[]

## Other responses

- `400` — Invalid request
- `500` — Server error

## Changes

- **2026-09-22** `c42250b855e4` — 1 warning
  - removed the request property `definition/name`
- **2026-09-21** `ca8fb37253e5` — 1 info
  - endpoint added
- **2026-09-18** `0fb60b40c570` — 1 breaking
  - api path removed without deprecation
- **2026-09-15** `306accd8ee26` — 4 breaking
  - the request property `definition/metrics` became required
  - the request property `definition/shape` became required
  - the request property `definition/variables/items/type` became required
  - the `definition/metrics` request property's minItems was increased to `1`
- **2026-09-15** `cb3984fd3acb` — 10 breaking, 5 warning, 25 info
  - request property `definition/filters/items/op` was restricted to a list of enum values
  - request property `definition/metrics/items/` was restricted to a list of enum values
  - request property `definition/sort/items/dir` was restricted to a list of enum values
  - request property `definition/time/grain` was restricted to a list of enum values
  - …36 more

[Full history](https://skmtc.dev/flexprice/apis/flexprice-api/changes/analytics/query/post.md)

---

[API](https://skmtc.dev/flexprice/apis/flexprice-api.md) · [All operations](https://skmtc.dev/flexprice/apis/flexprice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexprice/apis/flexprice-api/revisions/19bac1b92501?raw)