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.
advertising:writeGrant 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) andplatforms(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:ascordesc(default). Nulls sort last.limit(optional, 1-10,000, default 1,000): row cap;truncatedis 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):csvorxlsx; 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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.