# Amazon Ads API Reporting: Profiles, Auth and Limits

> How the Amazon Ads API delivers reports: Login with Amazon auth, profiles, the v3 create, poll and download flow, Reporting v1, Marketing Stream and limits.

- Canonical URL: https://www.vexio.ai/insights/amazon-ads-api-reporting-explained/
- Published: 2026-10-14
- Updated: 2026-10-14
- Category: Ad automation
- Author: Vexio engineering team

## Amazon Ads API reporting in five steps

A report request in the Amazon Ads API follows the same five steps whichever reporting surface you use:

1. **Get consent.** The advertiser authorizes your Login with Amazon (LwA) application. You trade the one-time code for an access token and a refresh token.
2. **Pick the account.** Call `GET /v2/profiles` on the right regional host and keep the profile ID (or, for some APIs, the account ID).
3. **Create the report.** Send a date range, the report type or fields you want, and a format. The response holds a report ID and the status `PENDING`.
4. **Poll.** Check the report until its status is `COMPLETED`.
5. **Download.** Fetch the file from the pre-signed link in the response and load it.

Everything below was checked against Amazon's developer documentation on 2026-10-14 (page names are listed under Sources). Amazon changes these pages often, so treat them as the authority and this article as a map.

## How does Amazon Ads API authorization work?

Two parties take part: the advertiser, who grants consent, and a client application registered with Login with Amazon and approved by Amazon Ads for API access ([authorization overview](https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/overview)). The flow is OAuth 2.0:

1. The advertiser opens a consent URL tied to your client ID. Amazon serves it from one of three regional hosts, with the scope `advertising::campaign_management` for most uses.
2. Login with Amazon redirects back to your return URL with an authorization code. Exchange it within 5 minutes.
3. Post the code, client ID and client secret to the token URL. You receive an access token (valid for 60 minutes) and a refresh token. Amazon states the resulting tokens are valid across all regions.
4. Later, post the refresh token to the same token URL to mint new access tokens without asking the advertiser again.

Refresh tokens deserve a calendar entry. Amazon states that tokens issued on or after 30 July 2026 expire 365 days after the advertiser's consent, while earlier tokens stay valid until revoked ([refresh tokens](https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/refresh-tokens)). A lapsed or revoked token returns HTTP 400 with `invalid_grant`. In a pipeline that looks like a silent data gap unless something alerts on it.

### Profiles, headers and regional hosts

A profile is an advertiser account in one marketplace. `GET /v2/profiles` needs no scope header, returns at most 5,000 items, and lists only profiles in the region of the host you call ([profiles](https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/profiles)). Each profile carries a country code, currency code and time zone. Store them: they decide how to read dates and money in that marketplace's reports.

The three API hosts are `advertising-api.amazon.com` (North America), `advertising-api-eu.amazon.com` (Europe) and `advertising-api-fe.amazon.com` (Far East). Each covers a defined list of marketplaces ([first call guide](https://advertising.amazon.com/API/docs/en-us/guides/get-started/first-call)).

Header names are not uniform across Amazon's pages. The authorization overview names `Amazon-Advertising-API-ClientId`; the version 3 tutorial and first-call guide name `Amazon-Ads-ClientId`. The profile ID goes in `Amazon-Advertising-API-Scope`, and the account ID in `Amazon-Ads-AccountId`, which the first-call guide lists for reporting and cross-product operations. Copy header names from the reference page of the endpoint you call, not from another guide.

## How do Amazon Ads API v3 reports work?

Version 3 uses one endpoint to create reports, `POST /reporting/reports`, with the content type `application/vnd.createasyncreportrequest.v3+json` ([get started with version 3 reports](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/get-started)). The body names the date range, the ad product, a `reportTypeId` such as `spCampaigns`, a `groupBy` level, the columns you want, a `timeUnit` of `DAILY` or `SUMMARY`, and a format (`GZIP_JSON`).

Then:

- **Poll** with `GET /reporting/reports/{reportId}`. The status moves from `PENDING` or `PROCESSING` to `COMPLETED`. Amazon says generation can take up to three hours. The response also has a `failureReason` field, so log it.
- **Download** from the `url` field, a link to S3. Decompress the gzip and read JSON.

Three details trip people up:

- You only get the columns you request. Use `date` with `DAILY`, and `startDate` and `endDate` with `SUMMARY`.
- A duplicate request with identical parameters while one is outstanding returns status 425, meaning too soon. Wait for the first report.
- Campaign names and budgets belong in an export, joined on the ID, rather than in reports ([reporting overview](https://advertising.amazon.com/API/docs/en-us/guides/reporting/overview)).

### Report types, date ranges and retention

Version 3 organizes reports by what you group on: campaign, ad group, ad, targeting, search term, placement, advertised product, purchased product, gross and invalid traffic, and several DSP-specific types, with availability that varies by ad product ([report types](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview)). Sponsored Products, Sponsored Brands, Sponsored Display, Sponsored Television and DSP each have their own `reportTypeId`. The [Amazon DSP explainer](https://www.vexio.ai/insights/amazon-dsp-explained/) covers what the DSP side measures.

Limits are set per report type. For campaign reports, Amazon lists a maximum date range of 31 days and these retention periods ([campaign reports](https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign)):

| Ad product | Campaign report retention |
|---|---|
| Sponsored Products | 95 days |
| Sponsored Television | 95 days |
| Sponsored Display | 65 days |
| Sponsored Brands | 60 days |

A backfill is therefore a series of requests of at most 31 days each, and history older than the retention window cannot be recovered from the API. Keep what you load.

## Reporting API v1: how it differs from v3

Amazon's version 3 pages carry a notice that the API will be deprecated on 30 June 2027 and point to the Reporting API v1 ([Reporting v1 overview](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/overview), [quickstart](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/quickstart)). The main differences:

- **Fields instead of report types.** You request dimension and metric fields such as `campaign.id`, `date.value` and `metric.impressions`. Time is a dimension, so a daily report means including `date.value`.
- **Different endpoints.** Create with `POST /adsApi/v1/create/reports`, check with `POST /adsApi/v1/retrieve/reports`. Statuses are `PENDING`, `PROCESSING`, `COMPLETED` and `FAILED`, and Amazon recommends checking about once per minute.
- **Several accounts per request.** One request can name up to five accounts, including manager accounts ([helpful concepts](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/helpful-concepts)).
- **Partitioned output.** `PARTITIONED_GZIP_JSON` and `PARTITIONED_CSV` split a report into parts of up to 1 GB uncompressed, each with its own link ([file formats](https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/new-features)).
- **Redefined metrics.** Conversion metrics lose the 1d, 7d, 14d and 30d suffixes and are reported on the traffic date, not the conversion date. Amazon warns that some DSP metrics now use broader definitions that include halo conversions, so mappings need review.

The v1 pages in Sources do not state a maximum date range or retention window. Check the API reference before sizing backfills.

## What is Amazon Marketing Stream?

Amazon Marketing Stream pushes advertising data to AWS instead of making you poll for it. Amazon's reporting overview describes version 2 as the primary programmatic reporting surface and recommends it for new integrations and recurring reporting at scale ([reporting overview](https://advertising.amazon.com/API/docs/en-us/guides/reporting/overview)).

| | Stream version 1 | Stream version 2 |
|---|---|---|
| Destination | Amazon Data Firehose or an SQS queue | S3 bucket you own, plus an SQS notification queue |
| Format | JSON | Apache Parquet |
| Values | Deltas per time window | Total value per time window |
| Frequency | Hourly | Intervals as short as 15 minutes |
| Datasets | Per ad product, such as `sp-traffic` and `sp-conversion` | Unified, such as `ads-performance-v1` (hourly) and `ads-converted-product-v1` (daily) |
| Status | Shut off after 30 June 2027 | Recommended for new integrations |

Source for the table: [Stream overview](https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/overview), [datasets](https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/datasets/overview) and [v1 data guide](https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/data-guide).

Version 2 delivers at least once and with no ordering guarantee. A restated record arrives again as a new version of the same key, and you keep the row with the highest `streamBatch.version` ([data delivery](https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/data-delivery)). A new subscription also receives historical data for the dataset's restatement period. Amazon's overview says there is no polling or throttling with Stream, and an automated backfill of up to 70 days on subscription creation.

## What are the Amazon Ads API rate limits for reports?

Amazon returns HTTP 429 when you send too many requests, with a `Retry-After` header giving the seconds to wait ([rate limiting](https://advertising.amazon.com/API/docs/en-us/reference/concepts/rate-limiting)). Report limits depend on the size of the report queue in each region, so they drop at busy times. Amazon recommends exponential backoff, longer backoff for report generation, and spreading backfills across the day in smaller slices.

For Reporting v1, Amazon documents one running report per advertiser, which it says allows roughly 100 reports per day. A request made while another is running is queued or gets a 429. Practical rules:

- Serialize report requests per advertiser account.
- Honour `Retry-After` and add jitter to your own backoff.
- Persist the report ID as soon as you receive it, so a crash during polling does not create a duplicate request.
- Run backfills in small slices, outside busy hours.

## How fresh is Amazon Ads API data?

Amazon states that initial impression and click data for sponsored ads is available through the API within 12 hours, and recommends waiting at least five days for accurate click data, since its invalid traffic system monitors for up to 30 days. Conversion data is refreshed and validated at daily, weekly and monthly intervals and can change for up to 60 days back. Amazon recommends re-retrieving reports monthly ([reporting overview](https://advertising.amazon.com/API/docs/en-us/guides/reporting/overview)).

Loading a day once is therefore not enough. Re-pull a rolling window of recent days on every run and a wider window less often, and merge on a natural key so repeats are harmless. [Idempotent ad reporting pipelines](https://www.vexio.ai/insights/idempotent-ad-reporting-pipelines-backfills-late-data/) covers the load pattern. For how restated attributed sales change a ratio such as ACOS, see [ACOS vs TACoS](https://www.vexio.ai/insights/acos-vs-tacos/).

## Which Amazon Ads API reporting surface fits?

| Need | Fit according to Amazon's documentation |
|---|---|
| Recurring data at scale, intraday freshness, many accounts | Stream version 2 |
| Ad hoc or scheduled reports with chosen dimensions | Reporting API v1 |
| An existing integration on version 3 | Keep it running and plan the migration before 30 June 2027 |
| Campaign names, budgets, status | Exports, joined on IDs |

Sales, orders and inventory for the seller's own business come from a different API with different credentials. [Selling Partner API vs Amazon Ads API](https://www.vexio.ai/insights/amazon-sp-api-vs-amazon-ads-api/) shows how the two fit together, and the [Amazon platform page](https://www.vexio.ai/platforms/amazon/) covers the wider Amazon advertising picture. If you are deciding whether to build the extraction at all, [marketing ETL explained](https://www.vexio.ai/insights/marketing-etl-explained/) lays out the moving parts.

## Where Vexio fits

Vexio builds and operates Amazon Ads extraction as part of custom advertising data pipeline engagements: authorization and token renewal, report creation and polling with throttle-aware retries, backfills inside the documented limits, a rolling re-pull of recent days, and loading into a warehouse such as BigQuery or PostgreSQL. Which reporting surface to target is settled during scoping, based on freshness needs and your cloud stack. See the [advertising data pipelines page](https://www.vexio.ai/etl/) or [request a demo](https://www.vexio.ai/demo/).

## Sources

Checked on 2026-10-14. Amazon Ads API documentation:

- https://advertising.amazon.com/API/docs/en-us/guides/reporting/overview (surfaces, shut-off dates, freshness, v1 concurrency)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/get-started (v3 create, poll, download, headers, 425)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/overview (v3 report type families)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/v3/report-types/campaign (date range, retention)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/overview (Reporting v1 changes)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/quickstart (v1 endpoints and statuses)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/helpful-concepts (accounts per request)
- https://advertising.amazon.com/API/docs/en-us/guides/reporting/ads-v1/new-features (partitioned formats)
- https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/overview (Stream v1 and v2 comparison)
- https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/datasets/overview (v2 datasets)
- https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/v2/data-delivery (delivery model)
- https://advertising.amazon.com/API/docs/en-us/guides/amazon-marketing-stream/data-guide (v1 datasets)
- https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/overview (OAuth flow, headers)
- https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/authorization-grants (consent hosts, token URLs)
- https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/refresh-tokens (365-day expiry)
- https://advertising.amazon.com/API/docs/en-us/guides/account-management/authorization/profiles (profiles)
- https://advertising.amazon.com/API/docs/en-us/guides/get-started/first-call (regional hosts, headers)
- https://advertising.amazon.com/API/docs/en-us/reference/concepts/rate-limiting (429, Retry-After)

## Frequently asked questions

### How does Amazon Ads API reporting work?

Reporting is asynchronous. The advertiser authorizes your Login with Amazon application, you identify the account with a profile ID, create a report request, poll its status until it is completed, then download the file from a pre-signed link. Amazon documents version 3 reporting, the newer Reporting API v1 and Amazon Marketing Stream as the available surfaces.

### What is a profile in the Amazon Ads API?

A profile represents an advertiser account in one marketplace. You list profiles with GET /v2/profiles on the regional host that covers the marketplace. Most calls need the profile ID in the Amazon-Advertising-API-Scope header, and each profile also carries a country code, currency code and time zone that you should store for reading report dates and money.

### How long do Amazon Ads API reports take to generate?

Amazon states that a version 3 report can take up to three hours to generate. Initial sponsored ads impression and click data is available within 12 hours, and conversion data can change for up to 60 days. Poll with a delay between requests, and do not resend an identical request while one is outstanding, because Amazon answers with status 425.

### Is the Amazon Ads API v3 reporting being deprecated?

Amazon's version 3 pages state that the reporting API will be deprecated on 30 June 2027, and its overview lists version 2 reporting and Amazon Marketing Stream version 1 with the same shut-off date. For new work, Amazon points to the Reporting API v1 for scheduled reports and Marketing Stream version 2 for recurring reporting at scale.

### What are the Amazon Ads API rate limits for reports?

Amazon says report limits are dynamic and depend on the size of the report queue in each region, so they tighten at busy times. A 429 response includes a Retry-After header. Use exponential backoff, spread backfills through the day, and note that Reporting API v1 allows one running report per advertiser at a time.

### What is Amazon Marketing Stream?

Amazon Marketing Stream is a push service that delivers advertising data to AWS destinations you own instead of requiring repeated API calls. Version 1 delivered JSON deltas to Amazon Data Firehose or SQS. Version 2 writes Parquet files with total values to an S3 bucket, with an SQS notification for each delivery, at intervals as short as 15 minutes.

---

Source: Vexio, https://www.vexio.ai/insights/amazon-ads-api-reporting-explained/
Talk to Vexio: request a demo at https://www.vexio.ai/demo/, call +1 778 896 4353 or email hello@vexio.ai.