Run an attribution query by UTM source, campaign, or ad

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,
  "timezone": "America/New_York"
}
'

{
  "results": [
    {
      "dateRange": {
        "start": "2026-04-01",
        "end": "2026-04-30"
      },
      "dimension": "<string>",
      "filter": {
        "and": [
          {
            "field": "orders.source_name",
            "op": "equals",
            "value": "<string>"
          }
        ]
      },
      "data": {
        "primary": [
          {}
        ]
      },
      "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"
        }
      ]
    }
  ]
}

{
  "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 Attribution board. Use it to count new customers per Meta ad set, rank campaigns by attributed revenue against their spend, or export credit by UTM source on a schedule. How attribution works explains how credit is assigned.

​

Breakdown dimensions

dimension decides what each row is. Each row also carries the platform IDs for its grain when the click had them. 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 with no matching platform data shows its raw ID or UTM value as the name. Rows with no value show (not set). The schema accepts other dimension values, but they return source-level rows, so stick to these eight.

​

Attribution model and window

• first_click credits the earliest touchpoint in the window, and last_click the latest. Visits with no detectable source only win when the customer has no other visit in the window.
• any_click credits every source the customer clicked, so rows add up to more than the total. Don’t sum them.
• attributionWindow is how many days before the order (or the conversion event, with valueSource: events) to look for touchpoints. -1 means no limit.

​

Filtering results

filters takes the canonical filter tree. Two families of fields work here. To filter by campaign ID, put the ID in attribution.utm_campaign. The channel.* fields, such as channel.campaign_id, belong to the ad-listing endpoints and return 500 here. A value matches every row whose name or ID equals it, across sources, so add an attribution.utm_source condition when the same name appears in more than one channel. orders.* conditions support their full operator set, but only with valueSource: orders. With valueSource: events they’re ignored.

​

Order settings aren’t applied for you

The web app applies your saved order settings (pending and voided orders, refund dating, exclusion filters) to attribution. This endpoint only uses the orderSettings you send. Without them, pending and voided orders count and nothing is excluded. To match the board, read them with Get order settings and pass the returned object as orderSettings. Order settings only apply with valueSource: orders.

​

Reading the response

• results has one entry with dateRange, dimension, the filter you sent, data.primary, and measureDetails.
• data.primary holds one row per dimension value, sorted by orders.count (or core.conversions with valueSource: events), highest first. row_number gives the position.
• Each row carries every measure for the value source, keyed by measure id. valueSource: orders returns orders.* measures (orders, new customers, revenue, margins). valueSource: events returns core.conversions, core.unique_converters, core.conversion_value, core.average_conversion_value, core.cpa, and core.roas. Both add channel.* spend and click measures and tracked.* visitor counts. measureDetails[].measure lists every measure id the rows carry, with its total.
• Values come back as numeric strings (for example "66930.1000"). A value of zero comes back as null. Parse both before doing math.
• Each row carries utm_source, the column named by dimension, and the ID columns in the table above. utm_adset and utm_ad appear on every row, but only hold the row’s own ad set or ad at those two grains, so ignore them elsewhere.

​

Errors and edge cases

• A malformed filters tree returns 400 with the reason in errors.
• A filter field this endpoint doesn’t accept, an unknown field, or an operator the field doesn’t list returns 500 with the reason in message, for example Filter field "channel.campaign_id" is not valid for context "attribution".
• When the query itself fails, the response is 200 with an empty body and no results. Treat that as “no answer”, not “no conversions”.
• Ad set and ad breakdowns over long ranges can time out with 502. Shorten the date range and retry.
• Without timezone, dates are read as UTC days. dateRange.end is inclusive.
• 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.

​

Related

• upstack query-attribution runs the same query from the CLI.
• List filter fields for the fields and operators each endpoint accepts.
• Get order settings for the orderSettings to pass.
• Run an analytics query for unattributed totals and time series.
• Set up UTM parameters so clicks land in the right campaign.