Run an attribution query

Attribute conversions across marketing touchpoints. Supports first-click, last-click, and any-click models with a fixed-set lookback window.

Required scope: analytics:read.

POST /db-mgmt/api/query-attribution

cURL

firstClickByUtmSource

curl --request POST \
  --url https://api.upstackdata.com/db-mgmt/api/query-attribution \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "pixelId": "5f1e6a4f-...",
  "dimension": "utm_source",
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  },
  "attributionModel": "first_click",
  "attributionWindow": 30
}
'

200

{
  "results": [
    {
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "dimension": "<string>",
      "data": {
        "primary": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ],
        "compare": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ]
      },
      "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"
        }
      ]
    }
  ]
}

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.

dimension · string · required

Dimension to attribute by (e.g. utm_source).

dateRange · object · required

Show child attributes

attributionModel · enum<string> · required

Available options: first_click, last_click, any_click

attributionWindow · enum<integer> · required

Attribution window in days. -1 means unlimited.

Available options: 1, 7, 14, 30, 60, 90, -1

filters · All of (and) · object

Canonical filter applied to the attribution result set. attribution.utm_* fields and orders.* fields are valid in this context — discover the full set via GET /api/filters.

All of (and)

Any of (or)

Not

Show child attributes

timezone · string

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. Defaults to USD when omitted — if your store sells in another currency, pass this explicitly.

valueSource · enum<string> · default: orders

Source of truth for conversion data.

Available options: orders, events

conversionEvent · string · default: purchase

Required when valueSource = events. Defaults to purchase when valueSource = orders.

orderSettings · object

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

Show child attributes

Response

200

application/json

Attribution results.

results is absent when the attribution query couldn't be run — the response is then an empty object with a 200. Treat a missing results as "no answer", not as "no conversions": an empty results array is the real no-data case.

results · object[]

Show child attributes