Skip to main content

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.

Required scope: advertising:write

Grant 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) and platforms (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: asc or desc (default). Nulls sort last.
    • definition.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.

Schedule fields

  • frequency (optional, nullable): daily, weekly or monthly.
  • 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) and timezone (optional, any IANA zone, default the app timezone).
  • format (optional): csv or xlsx, 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 show has_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​

Created

Response Headers
    Content-Type