upstack query-attribution

upstack query-attribution shows which UTM source, campaign, ad set, or ad gets credit for your orders, with revenue, new customers, spend, and ROAS on every row. It wraps Run an attribution query, which has the full request and response reference. How attribution works explains how credit is assigned.

Usage

upstack query-attribution \
  --dimension utm_adset \
  --model last_click \
  --window 30 \
  --date-start 2026-10-01 \
  --date-end 2026-10-07

Breakdown dimensions

--dimension decides what each row is. The CLI rejects any other value before sending the request.

`--dimension`	One row per	ID columns on the row	Filter field for the same grain
`utm_source`	Traffic source (`Meta Ads`, `Google Ads`, `Klaviyo`, `Direct / (not set)`)	`mktAccountId`	`attribution.utm_source`
`utm_medium`	Source and medium	`mktAccountId`	none (see Filters)
`utm_campaign`	Campaign	`mktAccountId`, `mktCampaignId`	`attribution.utm_campaign`
`utm_source_campaign`	Source and campaign	`mktAccountId`	`attribution.utm_campaign`
`utm_adset`	Ad set	`mktAccountId`, `mktAdsetId`	`attribution.utm_adset`
`utm_term`	Ad set, keyed on `utm_term`	`mktAccountId`, `mktAdsetId`	`attribution.utm_term`
`utm_ad`	Ad	`mktAccountId`, `mktAdId`	`attribution.utm_ad`
`utm_content`	Ad, keyed on `utm_content`	`mktAccountId`, `mktAdId`	`attribution.utm_content`

Names come from your connected ad platform when the click’s IDs match its data, otherwise from the UTM value on the click. A campaign without matching platform data shows its raw ID as the name. Rows with no value show (not set).

Required flags

Flag	Description
`--dimension <d>`	One of the eight dimensions above.
`--model <m>`	`first_click`, `last_click`, or `any_click`. `any_click` credits every source the customer clicked, so its rows add up to more than the total.
`--window <days>`	Days before each conversion to look for touchpoints: `1`, `7`, `14`, `30`, `60`, `90`, or `-1` for no limit.
`--date-start <YYYY-MM-DD>` `--date-end <YYYY-MM-DD>`	Conversions in this range are attributed. The end date is included.

Optional flags

Flag	Description	Default
`--filter <json>`	Canonical filter as JSON. See Filters.
`--value-source <s>`	`orders` counts store orders and returns `orders.` measures. `events` counts the tracked event in `--conversion-event` and returns `core.` conversion measures.	`orders`
`--conversion-event <name>`	Tracked event to count, in `snake_case` (e.g. `lead`). Required with `--value-source events`. Ignored for `orders`.
`--order-settings <json>`	Order settings to apply, as JSON. Saved settings aren’t applied for you: without this flag, pending and voided orders count and no exclusion filters run. Pass the output of `upstack account settings order show` to match the web app. Only used with `--value-source orders`.
`--timezone <tz>`	IANA timezone the dates are read in.	`UTC`, or your `config set timezone` value
`--currency <code>`	ISO 4217 code to convert money measures to. See Reporting currency.	`USD` (server default), or your `config set currency` value

-i, --output, --file, and --from-file work as described in upstack query shared flags. --output table and csv print one line per row with every measure column.

Filters

--filter takes the same canonical tree as every query command. Two families of fields work here.

Field	Matches	Example value
`attribution.utm_source`	Source name	`"Meta Ads"`
`attribution.utm_campaign`	Campaign name or platform campaign ID	`"DELFINA- CBO Winners"` or `"120226070802700013"`
`attribution.utm_adset`, `attribution.utm_term`	Ad set name or platform ad set ID	`"120244580584300013"`
`attribution.utm_ad`, `attribution.utm_content`	Ad name or platform ad ID	`"120244580583740013"`
`orders.customer_type`, `orders.order_type`, `orders.source_name`, `orders.value`, `orders.payment_gateway`, `orders.tags`	The order itself	`["new_customer"]`

To filter by campaign ID, put the ID in attribution.utm_campaign. Fields like channel.campaign_id belong to query-ads and query-channel-details, and this endpoint rejects them:

Error: API error (500): Filter field "channel.campaign_id" is not valid for context "attribution"

A value matches every row whose name or ID equals it, in any source. Add an attribution.utm_source condition when the same campaign name shows up under more than one channel.

attribution.* fields only do exact matches today. Use equals, or in for a list. upstack filters lists other operators for them, but those run as exact matches too: not_equals "Meta Ads" returns only Meta Ads. attribution.utm_medium conditions are ignored, and so are attribution.* conditions inside a not group. Keep conditions at the top level of an and, or in one or group under it. Details are in Filtering results.

orders.* conditions support every operator upstack filters lists for them, but only with --value-source orders. With events they’re ignored.

# One campaign by name
--filter '{"and":[{"field":"attribution.utm_campaign","op":"equals","value":"DELFINA- CBO Winners"}]}'

# The same campaign by its Meta campaign ID
--filter '{"and":[{"field":"attribution.utm_campaign","op":"equals","value":"120226070802700013"}]}'

# Two campaigns, mixing a name and an ID
--filter '{"and":[{"field":"attribution.utm_campaign","op":"in","value":["DELFINA- CBO Winners","15011273732"]}]}'

# Meta ad sets, new customers only
--filter '{"and":[{"field":"attribution.utm_source","op":"equals","value":"Meta Ads"},{"field":"orders.customer_type","op":"in","value":["new_customer"]}]}'

From-file schema

--from-file takes a JSON file of parameter-style keys, the same names as the flags, not the API request body. Flags override file values.

{
  "dimension": "utm_adset",
  "dateStart": "2026-10-01",
  "dateEnd": "2026-10-07",
  "model": "last_click",
  "window": 30,
  "timezone": "UTC",
  "currency": "USD",
  "valueSource": "orders",
  "conversionEvent": "purchase",
  "filter": { "and": [{ "field": "attribution.utm_campaign", "op": "equals", "value": "120226070802700013" }] },
  "orderSettings": { "countPendingOrders": false, "countVoidedOrders": false, "exclusionFilters": [] },
  "output": "json"
}

Response shape

results has one entry with dateRange, dimension, the filter you sent, data.primary, and measureDetails. The sample below is a real campaign-grain response, trimmed to a few of the measure columns.

{
  "results": [
    {
      "dateRange": { "start": "2026-10-01T00:00:00.000Z", "end": "2026-10-07T23:59:59.999Z" },
      "dimension": "utm_campaign",
      "filter": { "and": [{ "field": "attribution.utm_campaign", "op": "equals", "value": "120226070802700013" }] },
      "data": {
        "primary": [
          {
            "row_number": 1,
            "utm_source": "Meta Ads",
            "utm_campaign": "DELFINA- CBO Winners",
            "mktAccountId": "5172858979405730",
            "mktCampaignId": "120226070802700013",
            "orders.count": "337",
            "orders.total_revenue": "66930.1000",
            "orders.new_customers": "289",
            "channel.spend": "69883.9300"
          }
        ]
      },
      "measureDetails": [
        { "measure": "orders.count", "isSum": true, "primarySum": 337, "isCurrency": false }
      ]
    }
  ]
}

Rows are sorted by orders.count (or core.conversions with --value-source events), highest first.
With orders, rows carry orders.* measures. With events, they carry core.conversions, core.unique_converters, core.conversion_value, core.average_conversion_value, core.cpa, and core.roas. Both add channel.* ad platform measures and tracked.* visitor counts. measureDetails lists every measure id on the rows, with its total.
Values are numeric strings, and zero comes back as null.
utm_adset and utm_ad appear on every row but only hold the row’s own ad set or ad at those two grains.

Examples

# New customers per Meta ad set, last click, 7-day window
upstack query-attribution \
  --dimension utm_adset --model last_click --window 7 \
  --date-start 2026-10-01 --date-end 2026-10-07 \
  --filter '{"and":[{"field":"attribution.utm_source","op":"equals","value":"Meta Ads"}]}'

# One campaign by platform ID, as CSV
upstack query-attribution \
  --dimension utm_campaign --model last_click --window 30 \
  --date-start 2026-10-01 --date-end 2026-10-07 \
  --filter '{"and":[{"field":"attribution.utm_campaign","op":"equals","value":"120226070802700013"}]}' \
  --output csv --file campaign.csv

# Match the web app: apply your saved order settings as-is
upstack account settings order show > order.json
upstack query-attribution \
  --dimension utm_source --model first_click --window 7 \
  --date-start 2026-10-01 --date-end 2026-10-07 \
  --order-settings "$(cat order.json)"

# Lead events by campaign, no window limit
upstack query-attribution \
  --dimension utm_campaign --model first_click --window -1 \
  --value-source events --conversion-event lead \
  --date-start 2026-04-01 --date-end 2026-04-30

# Interactive
upstack query-attribution -i

Errors

Error	Cause
`Invalid --dimension "campaign". Valid attribution dimensions: ...`	`--dimension` isn’t one of the eight values. Nothing is sent.
`--filter must be valid JSON` / `--order-settings must be valid JSON`	The flag’s value didn’t parse. Nothing is sent.
`Validation error: ...`	The API returned `400`: the filter tree or another field has the wrong shape.
`API error (500): Filter field "..." is not valid for context "attribution"`	The field doesn’t apply here, such as `channel.campaign_id`. Use `attribution.utm_campaign`.
`API error (502): Internal server error`	Ad set or ad breakdowns over long ranges can time out. Shorten the date range.

See Errors and edge cases for the full list.

GETTING STARTED

ACCOUNT

DISCOVERY

QUERIES

DASHBOARDS

COSTS

PRODUCTS

ADVANCED

upstack query-attribution

Usage

Breakdown dimensions

Required flags

Optional flags

Filters

From-file schema

Response shape

Examples

Errors

See also

​Usage

​Breakdown dimensions

​Required flags

​Optional flags

​Filters

​From-file schema

​Response shape

​Examples

​Errors

​See also

Usage

Breakdown dimensions

Required flags

Optional flags

Filters

From-file schema

Response shape

Examples

Errors

See also