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": [
    {
      "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
        }
      ],
      "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 · object

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

Option 1

Option 2

Option 3

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

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