Run an analytics query

Execute a measures-and-dimensions query against your event stream. Mirrors the in-app query builder.

Required scope: analytics:read.

See Querying Data for a guided walkthrough.

POST /db-mgmt/api/query

cURL

minimal

curl --request POST \
  --url https://api.upstackdata.com/db-mgmt/api/query \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "pixelId": "5f1e6a4f-...",
  "granularity": "day",
  "measures": [
    {
      "measure": "orders.gross_revenue"
    },
    {
      "measure": "tracked.purchases"
    }
  ],
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  }
}
'

200

{
  "results": [
    {
      "granularity": "none",
      "dimensions": [
        "<string>"
      ],
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "compareDateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "measureDetails": [
        {
          "measure": "<string>",
          "isAverage": true,
          "isPercentage": true,
          "calculatedAverage": true,
          "success": true,
          "primaryAvg": 123,
          "compareAvg": 123,
          "primarySum": 123,
          "compareSum": 123,
          "percentDiff": 123,
          "hasPacing": true,
          "preferredTrendDirection": "up"
        }
      ],
      "data": {
        "primary": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ],
        "compare": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ]
      }
    }
  ]
}

Authorizations

x-api-key · string · header · required

Your Upstack API key. Starts with upstack_.

x-pixel-id · string · header · required

The pixel id the request targets.

Body

application/json

pixelId · string · required

Must match the x-pixel-id header (403 if it doesn't).

granularity · enum<string> · required

Available options: none, second, minute, hour, day, week, month, quarter, year

measures · object[] · required

Required array length: 1 - 30 elements

Show child attributes

dateRange · object · required

Show child attributes

dimensions · string[]

Maximum array length: 5

Dimension id (see Measures & Dimensions).

filters · All of (and) · object

Canonical filter applied to the query. Discover valid fields with GET /api/filters.

All of (and)

Any of (or)

Not

Show child attributes

compareDateRange · object

Optional comparison period. Must not overlap dateRange; the server picks the preceding period if omitted (and granularity ≠ none).

Show child attributes

timezone · string

IANA timezone (e.g. America/New_York).

currency · string · default: USD

ISO 4217 code to convert money measures to (e.g. EUR). Each amount converts at the rate for the day it occurred, so historical results stay stable across reruns. Defaults to USD when omitted — if your store sells in another currency, pass this explicitly.

orderSettings · object

Order-level query settings — exclusion filters, pending/voided handling.

Show child attributes

Response

200

application/json

Query results.

results · object[] · required

Show child attributes