Create Ad Report
POST/api/advertising/reports
Saves a report definition, optionally with a scheduled delivery by email and/or Slack. Scheduled reports are sent automatically at next_run_at.
advertising:writeGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Body fields
name(required, ≤ 150 chars).definition(required object) with these keys:definition.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.definition.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.definition.date_from/date_to(optional, Y-m-d, date_to on or after date_from): a fixed window.definition.relative_days(optional, 1-400): a trailing window ending yesterday; takes precedence over fixed dates. Defaults to 30 when no fixed window is given.definition.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.definition.sort(optional, ≤ 40 chars): a metric or dimension key; defaults to the first metric.sort_direction:ascordesc(default). Nulls sort last.definition.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.
Schedule fields
frequency(optional, nullable):daily,weeklyormonthly.day_of_week(optional, 1-7, ISO: 1 = Monday) for weekly;day_of_month(optional, 1-31; clamps to the month's last day) for monthly.time(optional, H:i, default 07:00) andtimezone(optional, any IANA zone, default the app timezone).format(optional):csvorxlsx, the attachment format for deliveries and the default for Export Saved Ad Report.email_recipients(optional, nullable, ≤ 20 emails).slack_webhook_url(optional, nullable): a Slack incoming-webhook URL (https://hooks.slack.com/services|workflows|triggers/…). It is never returned; responses showhas_slack_webhook.is_active(optional boolean): pause or resume the schedule.
next_run_at (UTC) is recomputed on every save; it is null when the report is inactive or has no frequency and recipients.
Returns 201 with the report. The creation is logged.
Requires the advertising.manage permission.
Also requires the advertising-manager feature (Advertising Manager plan); without it the endpoint returns 404.
Request
Responses
- 201
- 401
- 403
- 422
- 429
Created
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.