# Amazon Review Aggregates & Extended History Scraper (`dataspryva/amazon-review-aggregates-and-extended-history`) Actor

Collect Amazon customer reviews and rating summaries by product URL, ASIN, or keyword across 19 marketplaces, with star-rating and sort filters, reviewer images, and an optional session for deeper review history.

- **URL**: https://apify.com/dataspryva/amazon-review-aggregates-and-extended-history.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** E-commerce, Automation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.99 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Amazon Review Aggregates & Extended History Scraper

Pull customer reviews and rating summaries from any Amazon product across 19 marketplaces worldwide. Give it product URLs, bare ASINs, or search keywords, and it returns structured review records plus a per-product rating summary — star breakdown, total ratings count, and Amazon's own AI-generated "Customers say" summary.

### What this actor does

- Collects reviews from any Amazon product URL or bare ASIN, or discovers products automatically from search keywords/category URLs.
- Filters by star rating and sorts by most-helpful or most-recent.
- Optionally returns a per-product rating-aggregate record with the average rating, star histogram, total ratings count, and "Customers say" summary.
- Optionally accepts your own Amazon session so a product's review history can go beyond the default per-product cap, including a verified-purchases-only filter.
- Fields a review or product page doesn't provide (e.g. no reviewer images, no Vine Voice flag) are left out of that record.

### Output per review

| Field | Description |
|---|---|
| `productAsin` | Amazon ASIN of the reviewed product. |
| `ratingScore` | Star rating, 1–5. |
| `reviewTitle` / `reviewDescription` | Review headline and full text. |
| `reviewUrl` | Direct link to the individual review. |
| `reviewReaction` | Raw "N people found this helpful" text. |
| `reviewedIn` | Raw "Reviewed in \<country> on \<date>" text. |
| `isVerified` | Verified Purchase flag. |
| `isVineVoice` | Amazon Vine Voice reviewer flag, when evidenced. |
| `variant` | Product variant purchased (e.g. size/color). |
| `reviewImages` | Reviewer-uploaded image URLs, when `includeImages` is on. |
| `reviewVideos` | Reviewer-uploaded videos (`url`, `thumbnailUrl`), when present. |
| `position` | Rank of this review within its product's fetched set. |
| `reviewId` | Amazon's own review identifier. |
| `helpfulCount` | Parsed numeric helpful-vote count. |
| `reviewDate` | Parsed ISO date. |
| `reviewLocation` | Parsed reviewer country/region. |
| `sentimentHint` | Derived `positive` / `neutral` / `negative` label. |
| `wordCount` | Review length. |
| `hasImages` / `imageCount` / `hasVideos` / `videoCount` | Derived media counts. |
| `reviewerName` / `reviewerProfile` / `reviewerAvatar` | Reviewer identity fields, only present when `includeGdprSensitive` is `true`. |
| `collectionCompleteness` | Set to `"INLINE_SAMPLE"` only when a deeper fetch fell back to the default per-product sample. |
| `scrapedAt` | UTC timestamp of the scrape. |
| `sourceUrl` | The product URL that was scraped. |

### Output per product (rating aggregate)

When `includeAggregates` is on (default), one additional record per product carries:

| Field | Description |
|---|---|
| `type` | Always `"amazon_review_aggregate"`. |
| `productAsin` | Amazon ASIN. |
| `averageRating` | Overall star rating shown on the product page. |
| `globalRatingsCount` | Total number of ratings, not just the reviews fetched. |
| `starsBreakdown` | Count/percentage per star, 5 through 1. |
| `customersSay` | Amazon's AI-generated "Customers say" summary. |
| `customersSayAspects` | Per-aspect sentiment breakdown (`label`, `sentiment`, `mentionCount`, `summary`). |
| `productUrl` | Canonical `/dp/{ASIN}` product URL. |
| `collectionCompleteness` | Set to `"INLINE_SAMPLE"` only when a deeper fetch fell back to the default sample. |
| `scrapedAt` / `sourceUrl` | Scrape timestamp and source URL. |

#### Status records

If a run can't return real reviews for a product, the dataset gets one typed status record instead of being left empty, identified by its `type` value: `amazon_reviews_no_proxy`, `amazon_reviews_proxy_failed`, `amazon_reviews_walled_us`, `amazon_reviews_no_star_match`, `amazon_reviews_blocked`, `amazon_reviews_cookie_invalid`, `amazon_reviews_cookie_expired`, `amazon_reviews_cookie_robot_blocked`, `amazon_reviews_auth_required`, or `amazon_reviews_no_products_discovered`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `productUrls` | Array of strings | – | Amazon product URLs, or bare ASINs expanded using `country`. Leave empty to use `keywords`/`categoryUrls` instead. |
| `keywords` | Array of strings | `[]` | Search keywords to auto-discover products, used only when `productUrls` is empty. |
| `categoryUrls` | Array of strings | `[]` | Amazon search/category URLs to auto-discover products from, used only when `productUrls` is empty. |
| `maxProductsToDiscover` | Integer | `10` | Maximum products to discover from `keywords`/`categoryUrls` (1–50). |
| `includeAggregates` | Boolean | `true` | Emit one rating-aggregate record per product. |
| `sourceMode` | String (select) | `"AUTO"` | `AUTO` picks the deeper fetch automatically when a session is supplied, otherwise the default sample; `INLINE_ONLY` always uses the default sample and ignores a supplied session; `FULL_PAGE` always uses the deeper fetch and requires `cookieString`. |
| `onAuthRequired` | String (select) | `"RETURN_PARTIAL"` | Only used when `sourceMode` is `FULL_PAGE` without a valid `cookieString`: `FAIL` aborts the run, `RETURN_PARTIAL` falls back to the default sample and tags those records `collectionCompleteness: "INLINE_SAMPLE"`. |
| `proxyConfiguration` | Object | – | Required. An Apify proxy configuration; the actor exits cleanly with a status message if none is set. |
| `maxReviews` | Integer | `15` | Reviews per product (1–15). |
| `sortBy` | String (select) | `"helpful"` | `helpful` or `recent`. |
| `filterByStar` | String (select) | `""` (all) | Restrict to one star rating, `"1"`–`"5"`. |
| `includeImages` | Boolean | `true` | Extract reviewer-uploaded images. |
| `includeGdprSensitive` | Boolean | `false` | Include reviewer name, profile link, and avatar. |
| `country` | String (select) | `"amazon.com"` | Amazon marketplace domain (19 supported, e.g. `amazon.co.uk`, `amazon.de`, `amazon.in`, `amazon.com.br`). |
| `countryFallback` | Boolean | `true` | When the requested marketplace returns no reviews, retry the same ASIN on `amazon.ca` then `amazon.com.br`. Ignored when `cookieString` is set or `sourceMode` is `INLINE_ONLY`. |
| `cookieString` | String | `""` | Optional Amazon session (the `Cookie:` header value from a logged-in browser). When set, enables deeper review history and the verified-purchases filter. Never paste your password here. |
| `verifiedPurchasesOnly` | Boolean | `false` | Only return Verified Purchase reviews. Requires `cookieString`; has no effect otherwise. |
| `reviewerType` | String (select) | `""` | Explicit reviewer-type filter mirroring Amazon's own parameter. Requires `cookieString`; leave empty to use `verifiedPurchasesOnly` instead. |
| `cookieModeMaxReviews` | Integer | `500` | Maximum reviews per product when `cookieString` is set (1–2000). |
| `maxConcurrency` | Integer | `1` | Concurrent page fetches (1–5). |
| `requestTimeout` | Integer | `60` | Per-page timeout in seconds (30–180). |
| `retryCount` | Integer | `3` | Retries on blocked/failed fetches (1–10). |

#### Example: default review pull

```json
{
    "productUrls": ["https://www.amazon.com/dp/B09X7MPX8L"],
    "maxReviews": 15,
    "sortBy": "helpful",
    "proxyConfiguration": { "useApifyProxy": true }
}
```

#### Example: discover products by keyword, 5-star only

```json
{
    "keywords": ["wireless earbuds"],
    "maxProductsToDiscover": 5,
    "filterByStar": "5",
    "sortBy": "recent",
    "country": "amazon.co.uk",
    "proxyConfiguration": { "useApifyProxy": true }
}
```

#### Example: single marketplace, no fallback substitution

```json
{
    "productUrls": ["B09X7MPX8L"],
    "sourceMode": "INLINE_ONLY",
    "countryFallback": false,
    "country": "amazon.de",
    "proxyConfiguration": { "useApifyProxy": true }
}
```

#### Example: extended history with your own session

```json
{
    "productUrls": ["https://www.amazon.com/dp/B09X7MPX8L"],
    "cookieString": "session-id=123-4567890-1234567; ubid-main=123-4567890-1234567; at-main=Atza|...",
    "verifiedPurchasesOnly": true,
    "cookieModeMaxReviews": 500,
    "proxyConfiguration": { "useApifyProxy": true }
}
```

### Use cases

- **Voice-of-customer analysis** — pull review text and ratings for a product line to feed sentiment or keyword analysis.
- **Competitive benchmarking** — compare `averageRating`, `starsBreakdown`, and "Customers say" summaries across competing ASINs.
- **Review monitoring** — schedule runs on a watch-list of products to track new reviews, ratings, and helpful-vote counts over time.
- **Trust and quality signals** — surface `isVerified`/`isVineVoice` flags and reviewer-uploaded media for product-quality dashboards.
- **Localization research** — compare review tone and content for the same product across different marketplace domains.
- **Deeper brand research** — supply your own `cookieString` for longer review history on products you have a legitimate reason to review in depth.

### FAQ

**How many reviews can I get per product by default?**
Up to `maxReviews` (max 15) from Amazon's own "Top reviews" section on the product page — typically around 8-13 reviews are available there per ASIN, since Amazon doesn't expose deeper pagination to anonymous visitors.

**How do I get more than that?**
Supply your own Amazon session via `cookieString`. With a valid session, the actor can return up to `cookieModeMaxReviews` (default 500, max 2,000) per product and also supports the verified-purchases-only filter.

**Why did my `amazon.com` run come back with reviews in French or Portuguese?**
When `amazon.com` returns no reviews for an ASIN and `countryFallback` is on (default), the actor retries the same ASIN on `amazon.ca` then `amazon.com.br`. Reviews recovered this way reflect that marketplace's language. Set `countryFallback` to `false` for strict single-marketplace matching.

**Can I filter by verified purchases without a session?**
Not at fetch time — that filter requires `cookieString`. The `isVerified` flag is still returned on every review regardless, so you can filter it yourself downstream.

**Can I get reviews in another language?**
Yes — set `country` to the corresponding domain (e.g. `amazon.de` for German); reviews come back in that storefront's language.

**Why is `collectionCompleteness` present on some records?**
It's set to `"INLINE_SAMPLE"` only when `sourceMode` was `FULL_PAGE`, no valid `cookieString` was supplied, and `onAuthRequired` fell back to the default sample instead of failing — so you can tell those records aren't the deeper, paginated set.

**Do reviewer name, profile, and avatar always appear?**
No — only when `includeGdprSensitive` is set to `true`. Make sure you have a lawful basis before enabling it.

**Is this affiliated with Amazon?**
No. This is an independent, third-party actor that reads publicly available Amazon product and review pages and is not operated, endorsed, or sponsored by Amazon.com, Inc.

# Actor input Schema

## `productUrls` (type: `array`):

List of Amazon product URLs to scrape reviews from. Supports /dp/, /gp/product/, and /product/ URL formats across 19+ Amazon domains. A bare 10-character ASIN (e.g. "B09X7MPX8L", no URL) is also accepted -- it is expanded into a full URL using the `country` domain below. Leave empty and use `keywords`/`categoryUrls` instead to discover products automatically.

## `keywords` (type: `array`):

Search keywords used to auto-discover products when `productUrls` is empty (e.g. "wireless earbuds"). Fetches Amazon's public `/s?k=` search results page for each keyword and reviews up to `maxProductsToDiscover` resulting products.

## `categoryUrls` (type: `array`):

Advanced mode: supply your own Amazon `/s?...` or `/b?node=...` category/search URL(s) directly (used only when `productUrls` is empty). Products are discovered the same way as `keywords`.

## `maxProductsToDiscover` (type: `integer`):

Maximum number of products to discover per run from `keywords`/`categoryUrls`. Ignored when `productUrls` is supplied directly.

## `sourceMode` (type: `string`):

AUTO (default): use `cookieString` if provided, otherwise the cookie-free inline /dp/ sample. INLINE_ONLY: always use the cheap cookie-free inline sample (ignores `cookieString`), never escalates to a RESIDENTIAL proxy, and disables `countryFallback` -- the strictest, cheapest, single-marketplace path. FULL_PAGE: requires `cookieString` and always uses the paginated, authenticated /product-reviews/ fetcher; see `onAuthRequired` for what happens if no valid cookie is supplied.

## `onAuthRequired` (type: `string`):

What to do when `sourceMode=FULL_PAGE` is selected but no valid `cookieString` was supplied. FAIL: abort the run with a typed `amazon_reviews_auth_required` status message and no data. RETURN_PARTIAL (default): fall back to the cookie-free inline sample instead, tagging every returned review `collectionCompleteness: "INLINE_SAMPLE"` so downstream consumers know it is not the full paginated set. Ignored unless `sourceMode=FULL_PAGE`.

## `includeAggregates` (type: `boolean`):

Emit one additional `amazon_review_aggregate` record per product with the average rating, global ratings count, star histogram, and "Customers say" AI summary -- parsed from the same page HTML already fetched. These widgets render server-side even when individual review cards are gated, so this record is available more reliably than the reviews themselves.

## `country` (type: `string`):

Amazon country domain to scrape from. URLs from a different domain are honored automatically.

## `maxReviews` (type: `integer`):

Maximum number of reviews to scrape per product (1-15). Cookie-free mode is capped by Amazon's inline /dp/ review block, which renders ~8-13 top reviews per ASIN with no pagination.

## `sortBy` (type: `string`):

How to sort the reviews

## `filterByStar` (type: `string`):

Filter reviews by specific star rating (1-5). Leave empty for all ratings.

## `includeImages` (type: `boolean`):

Extract images uploaded by reviewers

## `includeGdprSensitive` (type: `boolean`):

Include reviewer names, profile links, and avatars. Set to false for GDPR compliance.

## `proxyConfiguration` (type: `object`):

REQUIRED. Uses the free AUTO (datacenter) proxy group by default. The actor automatically escalates to a RESIDENTIAL proxy for a retry pass if AUTO gets blocked or returns 0 reviews (skipped when `sourceMode=INLINE_ONLY`, or when you pin `apifyProxyGroups` to RESIDENTIAL yourself here).

## `countryFallback` (type: `boolean`):

When the requested `country` returns 0 review cards (e.g. amazon.com now ships an empty 'Customer reviews require account verification' block cookie-free), automatically retry amazon.ca then amazon.com.br with country-matched proxies. Ignored when `cookieString` is set, and forced off when `sourceMode=INLINE_ONLY`. Disable for strict single-marketplace matching.

## `cookieString` (type: `string`):

Optional. Provide your own Amazon session cookies — the literal `Cookie:` header value from a logged-in browser's DevTools Network tab (e.g. `session-id=123-456...; ubid-main=...; at-main=...`). When set, the actor switches to paginated /product-reviews/ mode and can return up to `cookieModeMaxReviews` reviews per product, including the verified-purchase filter. Never paste your Amazon password here — only the session cookie value.

## `cookieModeMaxReviews` (type: `integer`):

Maximum reviews to return per ASIN when `cookieString` is provided. Amazon caps pagination at ~50 pages x ~10 reviews = ~500 per filter combination; the actor fans out across star filters when this exceeds 500. Ignored in cookie-free mode.

## `verifiedPurchasesOnly` (type: `boolean`):

Only return reviews from Verified Purchases. Cookie mode only (requires `cookieString`) -- Amazon's cookie-free inline /dp/ block has no reviewerType-equivalent filter for anonymous sessions, so this has no effect without a cookie.

## `reviewerType` (type: `string`):

Explicit reviewerType filter, mirroring Amazon's own /product-reviews/ URL parameter. Cookie mode only -- has no effect without `cookieString`. Leave empty to use `verifiedPurchasesOnly` instead (or default to all reviews).

## `maxConcurrency` (type: `integer`):

Maximum number of concurrent browser pages

## `requestTimeout` (type: `integer`):

Timeout for each page request in seconds

## `retryCount` (type: `integer`):

Number of retries for failed requests / blocked sessions

## Actor input object example

```json
{
  "productUrls": [
    "https://www.amazon.com/dp/B09X7MPX8L"
  ],
  "keywords": [],
  "categoryUrls": [],
  "maxProductsToDiscover": 10,
  "sourceMode": "AUTO",
  "onAuthRequired": "RETURN_PARTIAL",
  "includeAggregates": true,
  "country": "amazon.com",
  "maxReviews": 15,
  "sortBy": "helpful",
  "filterByStar": "",
  "includeImages": true,
  "includeGdprSensitive": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "countryFallback": true,
  "cookieString": "",
  "cookieModeMaxReviews": 500,
  "verifiedPurchasesOnly": false,
  "reviewerType": "",
  "maxConcurrency": 1,
  "requestTimeout": 60,
  "retryCount": 3
}
```

# Actor output Schema

## `reviews` (type: `string`):

Dataset containing all scraped Amazon customer reviews.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "productUrls": [
        "https://www.amazon.com/dp/B09X7MPX8L"
    ],
    "keywords": [],
    "categoryUrls": [],
    "maxProductsToDiscover": 10,
    "sourceMode": "AUTO",
    "onAuthRequired": "RETURN_PARTIAL",
    "includeAggregates": true,
    "country": "amazon.com",
    "maxReviews": 15,
    "sortBy": "helpful",
    "includeImages": true,
    "includeGdprSensitive": false,
    "proxyConfiguration": {
        "useApifyProxy": true
    },
    "countryFallback": true,
    "cookieString": "",
    "cookieModeMaxReviews": 500,
    "verifiedPurchasesOnly": false,
    "reviewerType": "",
    "maxConcurrency": 1,
    "requestTimeout": 60,
    "retryCount": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/amazon-review-aggregates-and-extended-history").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "productUrls": ["https://www.amazon.com/dp/B09X7MPX8L"],
    "keywords": [],
    "categoryUrls": [],
    "maxProductsToDiscover": 10,
    "sourceMode": "AUTO",
    "onAuthRequired": "RETURN_PARTIAL",
    "includeAggregates": True,
    "country": "amazon.com",
    "maxReviews": 15,
    "sortBy": "helpful",
    "includeImages": True,
    "includeGdprSensitive": False,
    "proxyConfiguration": { "useApifyProxy": True },
    "countryFallback": True,
    "cookieString": "",
    "cookieModeMaxReviews": 500,
    "verifiedPurchasesOnly": False,
    "reviewerType": "",
    "maxConcurrency": 1,
    "requestTimeout": 60,
    "retryCount": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/amazon-review-aggregates-and-extended-history").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "productUrls": [
    "https://www.amazon.com/dp/B09X7MPX8L"
  ],
  "keywords": [],
  "categoryUrls": [],
  "maxProductsToDiscover": 10,
  "sourceMode": "AUTO",
  "onAuthRequired": "RETURN_PARTIAL",
  "includeAggregates": true,
  "country": "amazon.com",
  "maxReviews": 15,
  "sortBy": "helpful",
  "includeImages": true,
  "includeGdprSensitive": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  },
  "countryFallback": true,
  "cookieString": "",
  "cookieModeMaxReviews": 500,
  "verifiedPurchasesOnly": false,
  "reviewerType": "",
  "maxConcurrency": 1,
  "requestTimeout": 60,
  "retryCount": 3
}' |
apify call dataspryva/amazon-review-aggregates-and-extended-history --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/amazon-review-aggregates-and-extended-history"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OgPzorRclF6tasDvP/builds/xn6XVLwR6u2rvtGPw/openapi.json