List ads with daily spend and performance metrics

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

{
  "rows": [
    {
      "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
  }
}

{
  "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>"
      ]
    }
  ]
}

POST

db-mgmt

api

query-ads

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

{
  "rows": [
    {
      "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
  }
}

{
  "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 Use this to pull every ad with its campaign and ad set in one call, export daily spend per ad, or compare an ad’s last week against the week before. Each row is flat, so it maps straight onto a spreadsheet or a table in your warehouse.

Listing or metrics

Leave out measures for a listing: each row has the ad’s IDs, names, and basicDetails, and no data key.
Send measures and dateRange together to add data.primary, a daily series per ad. dateRange is required whenever measures has at least one entry.
Only ad-platform measures work here (channel.* and per-platform ids such as meta.spend or google.spend). Any other measure returns 400 with the unsupported ids. List available measures has the full catalog.
Days with no data for an ad are left out, so an ad that didn’t run in the range has an empty data.primary array.

Comparison periods

Send compareDateRange to add data.compare, a daily series for that period. It requires measures, and is rejected with 400 without them.
Nothing is compared unless you ask. There is no automatic preceding period.
A compareDateRange that overlaps dateRange is dropped without an error, so the rows only carry data.primary.

Filtering which ads come back

Every filter field this endpoint accepts narrows the ad list itself, so it also changes pagination.total.

Field	Matches	Operators
`channel.resource_source`	Platform: `facebookIntegration`, `googleAdsIntegration`, `tiktokIntegration`	`equals`, `not_equals`, `in`, `not_in`
`channel.account_id`, `channel.campaign_id`, `channel.adset_id`, `channel.ad_id`	Platform IDs	`equals`, `in`, `not_in`
`channel.resource_name` (the ad’s name), `channel.account_name`, `channel.campaign_name`, `channel.adset_name`, `channel.ad_name`	Names	`equals`, `not_equals`, `in`, `not_in`, `contains`, `not_contains`, `starts_with`, `ends_with`
`channel.resource_status`, `channel.resource_configured_status`, `channel.resource_effective_status`	Status values such as `ACTIVE` or `PAUSED`	`equals`, `not_equals`, `in`, `not_in`

orders.*, events.*, and attribution.* fields aren’t accepted here and return 400. To see which UTM campaign or ad gets credit for orders, use Run an attribution query.

Pagination and sorting

limit is 1 to 500 (default 50) and offset skips rows. Keep paging while pagination.hasMore is true. pagination.total counts every ad that matches filters.
Sort with sortBy (sourceUpdatedAt, sourceCreatedAt, or resourceName) and sortDirection (asc or desc, lowercase).

Currency

currency (default USD) converts both the daily measures and the budget fields in basicDetails (dailyBudget, budgetRemaining, amountSpent). Budget fields use the latest exchange rate. After conversion, basicDetails.currency is the currency you asked for and basicDetails.nativeCurrency is the ad account’s own currency.

Errors and edge cases

A filter field this endpoint doesn’t accept returns 400, for example Filter field "attribution.utm_campaign" is not valid for context "query_ads".
A measure that fails to compute leaves that measure out of data, but the request still returns 200 with the other measures.
A date-only dateRange.end covers that whole day. With timezone set, days are read in that zone, otherwise in UTC.
pixelId in the body must equal the x-pixel-id header, or the request returns 403.

upstack query-ads runs the same query from the CLI.
List channel entities for accounts, campaigns, or ad sets instead of ads.
List filter fields for the fields each endpoint accepts (query_ads).
List available measures for measure ids.

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).

measures

object[]

Ad-platform measures to add as a daily series per ad, over dateRange. Leave out for a listing with no metrics.

Maximum array length: 30

Show child attributes

dateRange

object

Required when measures is set. Ignored for a listing.

Show child attributes

compareDateRange

object

Optional comparison period. Requires measures. Dropped without an error when it overlaps dateRange.

Show child attributes

filters

All of (and) · object

Narrows which ads are listed. Only channel.* fields valid for query_ads are accepted. An or or not group can't mix basic-details and metric fields.

All of (and)
Any of (or)
Not

Show child attributes

timezone

string

IANA timezone used to read dateRange and bucket the daily series. Omit for UTC.

Example:

"America/New_York"

currency

string

default:USD

ISO 4217 code to convert measures and basicDetails budget amounts to (e.g. EUR). Defaults to USD when omitted. Each row reports the ad account's own currency in basicDetails.nativeCurrency.

limit

integer

default:50

Rows per page.

Required range: 1 <= x <= 500

offset

integer

default:0

Rows to skip.

Required range: x >= 0

sortBy

enum<string>

default:sourceUpdatedAt

Sort key. resourceName is the ad's name.

Available options:

sourceUpdatedAt,

sourceCreatedAt,

resourceName

sortDirection

enum<string>

default:desc

Sort direction, lowercase.

Available options:

asc,

desc

Response

Flat ads listing.

rows

object[]

required

Show child attributes

pagination

object

required

Show child attributes

OVERVIEW

ACCOUNT

CATALOG

ANALYTICS

DASHBOARDS

COSTS

PRODUCTS

EVENTS

List ads with daily spend and performance metrics

Listing or metrics

Comparison periods

Filtering which ads come back

Currency

Errors and edge cases

Authorizations

Body

Response

​Listing or metrics

​Comparison periods

​Filtering which ads come back

​Pagination and sorting

​Currency

​Errors and edge cases

​Related

Authorizations

Body

Response

Listing or metrics

Comparison periods

Filtering which ads come back

Pagination and sorting

Currency

Errors and edge cases

Related