Skip to main content

Run Ad Report

POST 

/api/advertising/reports/run

Runs an ad-hoc advertising report from a definition and returns the rows without saving anything. Each row carries a label and an <dimension>_id for every dimension plus the requested metrics; columns lists the column keys and labels in order. Ratios are fractions (0.1956 = 19.56%) and contribution-based metrics are null without product cost data. notes explains estimates, unmapped spend, currency caveats and truncation.

Required scope: advertising:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body fields

  • dimensions (required, may be empty, ≤ 4, distinct): platform, account, portfolio, label, campaign, campaign_type, ad_group, product, brand, target, match_type, search_term, date, week, month, weekday, hour.
  • metrics (required, 1-16, distinct): spend, sales, impressions, clicks, orders, units, acos, roas, ctr, cpc, cvr, attributed_contribution, contribution_after_ads, poas, net_poas, cover_days.
  • date_from / date_to (optional, Y-m-d, date_to on or after date_from): a fixed window.
  • relative_days (optional, 1-400): a trailing window ending yesterday; takes precedence over fixed dates. Defaults to 30 when no fixed window is given.
  • ad_account_ids, campaign_ids, label_ids, product_ids (optional integer arrays) and platforms (optional: amazon_ads, ebay, google_ads, walmart_connect, meta_ads, tiktok_ads): filters. Label IDs expand to every campaign the labels cover.
  • sort (optional, ≤ 40 chars): a metric or dimension key; defaults to the first metric. sort_direction: asc or desc (default). Nulls sort last.
  • limit (optional, 1-10,000, default 1,000): row cap; truncated is true when more rows existed.

Dimensions come from different ledgers (product/brand from item data, target/match_type from targets, search_term from search terms, hour from Amazon Marketing Stream); combining incompatible ones returns 422.

  • file_type (optional): csv or xlsx; accepted for parity with Export Ad Report and ignored here.

Requires the advertising.view permission.

Also requires the advertising-manager feature (Advertising Manager plan); without it the endpoint returns 404.

Money is in the tenant currency, except for reports with the hour dimension: hourly figures stay in each ad account's currency, so hourly rows carry a currency_code column (listed in columns as the Currency dimension) and are never summed across currencies. A report split by product whose rows exceed the roll-up cap returns partial figures (the highest-spend rows), with truncated: true and a note.

Request​

Responses​

OK

Response Headers
    Content-Type