Skip to main content
Every number on your Upstack dashboards comes from the same kind of query: one or more measures, an optional breakdown by dimensions, a date range, and optional filters. You can run that query yourself with Run an analytics query or with upstack query from the command line. Both need an API key with the analytics:read scope (see the API introduction). This page walks through each part of a query. The API and CLI references hold the full request and response details.

​
1. Pick measures

A measure is a number Upstack calculates, named by a namespaced id. The prefix tells you where the data comes from: To find an id, run upstack measures --search revenue or call List available measures. One request takes up to 30 measures. Each runs as its own query, so a measure that fails comes back with success: false while the others still return.

​
2. Choose a granularity

granularity decides the shape of the result:
  • day, week, month (or hour, quarter, year) return a time series with one row per period.
  • none returns one row per dimension value, sorted by the first measure, highest first.

​
3. Break down by dimensions

Dimensions split each measure into groups, up to five per query. List them with upstack dimensions. A measure can only be broken down by dimensions its data source records: Measures & Dimensions describes what each dimension holds.

​
4. Set the date range

dateRange takes a start and an end date, and the end date is included. Dates are read in the timezone you send (an IANA name such as America/New_York) or in UTC when you leave it out. See Timezones. Add compareDateRange to get a comparison period. It must not overlap the main range. Money measures come back in USD unless you send currency. See Reporting currency.

​
5. Add filters

Filters use a tree of and, or and not groups, at most three levels deep. Each leaf is { "field", "op", "value" }:
Fields you can use in a measures query: Operators are equals, not_equals, in, not_in, contains, not_contains, starts_with, ends_with, greater_than, less_than, greater_than_or_equals, less_than_or_equals, plus array_includes, array_includes_all and array_includes_any for orders.tags. Not every field takes every operator. upstack filters --detail and List filter fields show each field’s operators. Two rules return a 400 when broken:
  • A filter with a channel.* field can’t also contain fields from another namespace.
  • A channel.* filter only works when every measure in the query comes from ad platform data.
The attribution.utm_* fields only work in attribution queries.

​
Examples

Shopping funnel by day:
Net revenue by UTM source, highest first:
Sessions and conversion rate by device:
Spend and ROAS for prospecting campaigns:
Add --output csv --file ./report.csv to any of these to save the result as a CSV file.
The API doesn’t apply your saved order settings, such as excluded orders or refund dating, the way the dashboards do. Send them as orderSettings to match your dashboard numbers. Run an analytics query explains how.

Measures & Dimensions

What each measure and dimension means.

Custom Measures

Build your own measure from a formula over existing ones.

Attribution Reporting

Credit conversions to UTM sources and campaigns by attribution model.

upstack query

Every flag of the CLI query command.