Skip to main content

Export Ad Report

POST 

/api/advertising/reports/export

Runs an ad-hoc report definition and downloads the result as a CSV (default) or XLSX file named ads-report-YYYYMMDD-HHMMSS.<ext>, with one column per dimension label and metric.

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 (default) or xlsx.

Requires the advertising.view permission.

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

Request​

Responses​

OK

Response Headers
    Content-Type