Run an analytics query with measures and dimensions

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-2b7c-4d1e-9a3f-8c6b2e0d4a71",
  "granularity": "day",
  "measures": [
    {
      "measure": "orders.gross_revenue"
    },
    {
      "measure": "tracked.purchases"
    }
  ],
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-03"
  }
}
'

{
  "results": [
    {
      "granularity": "day",
      "dimensions": [],
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-03T23:59:59.999"
      },
      "measureDetails": [
        {
          "measure": "orders.gross_revenue",
          "isAverage": false,
          "isPercentage": false,
          "calculatedAverage": false,
          "success": true,
          "primaryAvg": 4126.5,
          "compareAvg": 3890.12,
          "primarySum": 12379.5,
          "compareSum": 11670.36,
          "percentDiff": 6.08,
          "hasPacing": false,
          "preferredTrendDirection": "up"
        },
        {
          "measure": "tracked.purchases",
          "isAverage": false,
          "isPercentage": false,
          "calculatedAverage": false,
          "success": true,
          "primaryAvg": 43,
          "compareAvg": 40.33,
          "primarySum": 129,
          "compareSum": 121,
          "percentDiff": 6.61,
          "hasPacing": false,
          "preferredTrendDirection": "up"
        }
      ],
      "data": {
        "primary": [
          {
            "dt": "2026-04-01T00:00:00.000",
            "orders.gross_revenue": 3980.25,
            "tracked.purchases": 41
          },
          {
            "dt": "2026-04-02T00:00:00.000",
            "orders.gross_revenue": 4412.1,
            "tracked.purchases": 46
          },
          {
            "dt": "2026-04-03T00:00:00.000",
            "orders.gross_revenue": 3987.15,
            "tracked.purchases": 42
          }
        ]
      }
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

POST

db-mgmt

api

query

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-2b7c-4d1e-9a3f-8c6b2e0d4a71",
  "granularity": "day",
  "measures": [
    {
      "measure": "orders.gross_revenue"
    },
    {
      "measure": "tracked.purchases"
    }
  ],
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-03"
  }
}
'

{
  "results": [
    {
      "granularity": "day",
      "dimensions": [],
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-03T23:59:59.999"
      },
      "measureDetails": [
        {
          "measure": "orders.gross_revenue",
          "isAverage": false,
          "isPercentage": false,
          "calculatedAverage": false,
          "success": true,
          "primaryAvg": 4126.5,
          "compareAvg": 3890.12,
          "primarySum": 12379.5,
          "compareSum": 11670.36,
          "percentDiff": 6.08,
          "hasPacing": false,
          "preferredTrendDirection": "up"
        },
        {
          "measure": "tracked.purchases",
          "isAverage": false,
          "isPercentage": false,
          "calculatedAverage": false,
          "success": true,
          "primaryAvg": 43,
          "compareAvg": 40.33,
          "primarySum": 129,
          "compareSum": 121,
          "percentDiff": 6.61,
          "hasPacing": false,
          "preferredTrendDirection": "up"
        }
      ],
      "data": {
        "primary": [
          {
            "dt": "2026-04-01T00:00:00.000",
            "orders.gross_revenue": 3980.25,
            "tracked.purchases": 41
          },
          {
            "dt": "2026-04-02T00:00:00.000",
            "orders.gross_revenue": 4412.1,
            "tracked.purchases": 46
          },
          {
            "dt": "2026-04-03T00:00:00.000",
            "orders.gross_revenue": 3987.15,
            "tracked.purchases": 42
          }
        ]
      }
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

{
  "message": "<string>",
  "errors": [
    {
      "message": "<string>",
      "key": "<string>",
      "path": [
        "<string>"
      ]
    }
  ]
}

Required scope: analytics:read This is the endpoint behind the numbers on your dashboards. Use it to pull daily gross revenue into a spreadsheet, rank UTM sources by new-customer revenue, or feed a BI tool on a schedule. Querying data walks through building a query step by step.

How the request shapes the response

Any granularity other than none returns a time series. data.primary has one row per bucket in the range, each with a dt field, including buckets with no data.
granularity: none returns one row per dimension combination, sorted by the first measure in measures, highest first.
Each row carries one value per measure, keyed by measure id, and one value per dimension, keyed by dimension id.
dateRange.end is inclusive. With timezone set, dates are read as local dates in that zone. Without it, they’re read as UTC. See Timezones.

Comparison periods

Send compareDateRange to get data.compare rows and comparison totals in measureDetails.
Leave it out and a time-series query still compares against the preceding period of the same length. measureDetails[].percentDiff uses that period, but the response leaves out compareDateRange and data.compare.
A compareDateRange that overlaps dateRange is dropped without an error, and a time-series query falls back to the preceding period.

Order settings aren’t applied for you

The web app applies your saved order settings (pending and voided orders, refund dating, exclusion filters) to every query. This endpoint only uses the orderSettings you send. To match the dashboard, read them with Get order settings and pass the returned object as orderSettings.

Errors and edge cases

A measure whose query fails comes back with success: false and zero totals in measureDetails. The request still returns 200, so check success before you treat a zero as real.
A malformed filters tree, or a filter field this endpoint doesn’t accept, returns 400 with the reason in errors. List filter fields shows which fields work here (query_measures).
currency is case-insensitive. A code that isn’t three letters falls back to USD without an error. See Reporting currency.
pixelId in the body must equal the x-pixel-id header, or the request returns 403.

List available measures for valid measure ids.
Run a cohort analysis for retention and LTV by acquisition period.
Run an attribution query for credit by UTM source or campaign.
upstack query runs the same query from the CLI.

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

Time bucket for result rows. none returns one row per dimension combination instead of a time series.

Available options:

none,

second,

minute,

hour,

day,

week,

month,

quarter,

year

measures

object[]

required

The measures to compute. Each one runs as its own query, so one failing measure doesn't fail the others.

Maximum array length: 30

Show child attributes

dateRange

object

required

Inclusive date range. A date-only end covers that whole day.

Show child attributes

dimensions

string[]

Break results down by these dimensions, e.g. utm_source or country. Unknown dimension ids are rejected with 400.

Maximum array length: 5

Dimension id (see Measures and dimensions).

filters

All of (and) · object

Filter applied to the query. Fields must list query_measures in their applicableContexts in List filter fields.

All of (and)
Any of (or)
Not

Show child attributes

compareDateRange

object

Optional comparison period. An overlapping range is ignored without an error. When it's absent and granularity isn't none, the server compares against the preceding period but leaves it out of the response.

Show child attributes

timezone

string

IANA timezone (e.g. America/New_York) that dateRange and compareDateRange are read in. Defaults to UTC.

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 settings to apply to this query. The query endpoints don't read the account's saved order settings, so pass them here to match the web app's numbers. The orderSettings object returned by Get order settings can be passed as-is.

Show child attributes

Response

Query results.

results

object[]

required

Query results. A cohort analysis always returns exactly one entry.

Show child attributes

OVERVIEW

ACCOUNT

CATALOG

ANALYTICS

DASHBOARDS

COSTS

PRODUCTS

EVENTS

Run an analytics query with measures and dimensions

How the request shapes the response

Comparison periods

Order settings aren’t applied for you

Errors and edge cases

Authorizations

Body

Response

​How the request shapes the response

​Comparison periods

​Order settings aren’t applied for you

​Errors and edge cases

​Related

Authorizations

Body

Response

How the request shapes the response

Comparison periods

Order settings aren’t applied for you

Errors and edge cases

Related