List channel entities with optional metrics

List ad accounts, campaigns, ad sets, or ads from the ads-platform integrations connected to your pixel, with optional metric aggregation over a date range.

Required scope: analytics:read.

POST /db-mgmt/api/query-channel-details

cURL

listingOnly

curl --request POST \
  --url https://api.upstackdata.com/db-mgmt/api/query-channel-details \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --header 'x-pixel-id: <api-key>' \
  --data '
{
  "pixelId": "5f1e6a4f-...",
  "granularity": "day"
}
'

200

{
  "results": [
    {
      "basicDetails": {},
      "data": {
        "primary": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ],
        "compare": [
          {
            "dt": "<string>",
            "start": "<string>",
            "end": "<string>"
          }
        ]
      }
    }
  ],
  "pagination": {
    "limit": 123,
    "offset": 123,
    "total": 123,
    "hasMore": true
  }
}

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

Available options: none, second, minute, hour, day, week, month, quarter, year

dimensions · enum<string>[]

At most one grain dimension: campaign, adset, or ad. Omit for account grain (default).

Maximum array length: 5

Available options: campaign, adset, ad

Example:

["campaign"]

measures · object[]

Optional. When set, aggregates the named measures over dateRange.

Maximum array length: 30

Show child attributes

dateRange · object

Required together with measures. Absent = entity-only listing.

Show child attributes

compareDateRange · object

Optional comparison period. Forbidden when measures is absent.

Show child attributes

filters · object

Canonical filter applied to the listing. Common shapes: scope by channel.resource_source (platform), channel.account_id (ad account), or channel.campaign_id (parent campaign for adset/ad grain).

Option 1

Option 2

Option 3

Show child attributes

timezone · string

IANA timezone.

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. Applies to results[].measures only: the basicDetails budget fields (dailyBudget, budgetRemaining, amountSpent) are point-in-time values from the ad platform and stay in their native currency, which each row reports in its own currency field.

limit · integer · default: 50

Required range: 1 <= x <= 500

offset · integer · default: 0

Required range: x >= 0

sortBy · enum<string> · default: sourceUpdatedAt

Available options: sourceUpdatedAt, sourceCreatedAt, resourceName

sortDirection · enum<string> · default: desc

Available options: asc, desc

Response

200

application/json

Listing results.

results · object[] · required

Show child attributes

pagination · object · required

Show child attributes