How does the Amazon Ads reporting API work?
The Amazon Ads reporting API is asynchronous, so getting a report runs in three stages:
- Request the report.
POSTto/reporting/reportswith the report configuration: ad product, report type, columns, grouping, date range and time unit. Amazon returns areportId. - Wait for it to generate. Check the report's status with that
reportIduntil it is done. Amazon decides how long that takes, up to three hours by its own guidance, and whether the report completes or fails, so the number of status checks varies. A duplicate request with identical parameters returns status425until the first one finishes. - Download the report once it is complete.
For API access and account setup, see the Amazon Ads API overview. For the separate retirement of the old sponsored ads and DSP report centers, see the Amazon Ads Agent reporting transition.
For performance data pushed to you in near real time instead, use Amazon Marketing Stream: hourly traffic and conversions delivered to your own AWS account.
What is the difference between version 3 reports and Ads API v1 reporting?
Version 3 reports are built around report types. Each request names a reportTypeId (such as spCampaigns or spSearchTerm), an ad product, a groupBy, the columns to return, and a timeUnit of SUMMARY or DAILY. Each report type carries its own limits: Sponsored Brands and Sponsored Display ad group reports, for example, allow a 31-day date range and keep 60 and 65 days of data.
Ads API v1 reporting is the newer interface, part of Amazon Ads API v1. It drops report types: you combine the dimensions you need in one report, and one report can span ad products. Retention is longer:
| Time dimension | Data retention | Longest date range in one report |
|---|---|---|
| Hour | 14 days | 14 days |
| Date | 15 months | 120 days |
| Month | 6 years | 25 months |
Amazon still advises keeping date ranges short: a long look-back with many dimensions and metrics can make a report fail on size.
How does an AI agent request Amazon Ads reports?
The Amazon Ads MCP carries Amazon's reporting operations as tools your AI client can call, listed in the Amazon Ads API tools reference. With every call it passes Amazon's current state to your AI, including the rate limit, when to retry and how long a report usually takes, so the AI decides when to wait or check again: see rate limits, throttling and long-running jobs. The Build the Right Amazon Ads Report Skill turns a familiar version 3 report request, or a plain metric question, into a validated Ads API v1 report request: it checks custom fields against the live reporting catalog, asks which report you mean when a name is ambiguous, and creates the report job only when you ask for it or approve it.
The guides below put Amazon Ads report data to work on specific decisions.
Choose the report from the decision, then preserve its grain
A useful reporting workflow connects the question, source, reporting period, and interpretation. A campaign-efficiency question needs attributed ad metrics. A business-level spend ratio needs total revenue as well. A search-funnel question may require Brand Analytics alongside advertising data. Choosing a familiar report name before defining the question can produce a precise answer to the wrong problem.
| Question | Source distinction | Supporting guide |
|---|---|---|
| Which search terms deserve a closer look? | Clicked ad activity, with product targets and branded terms separated | Search-term mining |
| What happened across the search funnel? | SQP funnel metrics differ from ad-attributed metrics | SQP and PPC signals |
| Is ad spend efficient for the campaign or the business? | ACoS uses attributed sales; TACoS uses total revenue | TACoS versus ACoS |
| Do we need recurring hourly delivery? | Stream records can be restated; ingestion must reconcile versions | Marketing Stream and Stream API setup |
| Did a DSP launch actually deliver? | A create response is not evidence of impressions | DSP campaign creation and verification |
An analysis report is not a campaign-change request. Review attribution completeness and data sufficiency before turning a search-term finding into a scoped proposal. Keep each source's period, account, dimensions, and metric definitions with its output. This hub covers report retrieval and selected uses; Amazon PPC strategy develops the optimization decisions and AMC measurement covers customer and exposure analysis.
What must stay consistent when reports are combined?
Keep the account, reporting period, dimensions, and attribution definition explicit. Dimensions determine the row: a query-by-campaign dataset cannot be joined directly to repeated query totals without checking for multiplication. Aggregate to the shared query and period before comparing SQP with paid data, as the unified keyword view explains.
ACoS is ad spend divided by attributed ad sales; TACoS is ad spend divided by total revenue. Both can use the same spend numerator, but their denominators answer different questions. Do not calculate either from a mixture of incompatible periods.
For Stream v2, records represent totals that can be restated. Keep the highest streamBatch.version for each full record key rather than summing every delivered version; the Stream API guide also covers unordered delivery and delete records. For search-term decisions, review click sufficiency and attribution before recommending a negative. The report identifies candidates; an approved, scoped request is still needed before a campaign change.