{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Review Aggregates & Extended History Scraper",
    "description": "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.",
    "version": "1.0",
    "x-build-id": "3eBuV9sO4ltC6gYLd"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/dataspryva~amazon-review-aggregates-and-extended-history/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-dataspryva-amazon-review-aggregates-and-extended-history",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/dataspryva~amazon-review-aggregates-and-extended-history/runs": {
      "post": {
        "operationId": "runs-sync-dataspryva-amazon-review-aggregates-and-extended-history",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/dataspryva~amazon-review-aggregates-and-extended-history/run-sync": {
      "post": {
        "operationId": "run-sync-dataspryva-amazon-review-aggregates-and-extended-history",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "productUrls": {
            "title": "Product URLs",
            "type": "array",
            "description": "List of Amazon product URLs to scrape reviews from. Supports /dp/, /gp/product/, /gp/aw/d/ 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.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Keywords (auto-discover products)",
            "type": "array",
            "description": "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.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "categoryUrls": {
            "title": "Category / Search URLs (auto-discover products)",
            "type": "array",
            "description": "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`.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxProductsToDiscover": {
            "title": "Max Products to Discover",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum number of products to discover per run from `keywords`/`categoryUrls`. Ignored when `productUrls` is supplied directly.",
            "default": 10
          },
          "extendedHistory": {
            "title": "Extended Review History",
            "type": "boolean",
            "description": "Merge Amazon's public extended review feed for each ASIN (no login, no cookie): up to 100 reviews per star/sort bucket, and walking every bucket yields 100-850+ unique reviews for popular US products, deduplicated against the product-page sample. Coverage varies by ASIN (some products expose few or no rows) and the feed carries Amazon.com reviews only; when off, only the ~8-13 product-page top reviews are returned.",
            "default": true
          },
          "mergeMarketplaces": {
            "title": "Merge Extra Marketplaces",
            "type": "array",
            "description": "Additional Amazon marketplaces whose product page is fetched for the same ASIN and whose reviews are merged (deduplicated by review ID and content). Each marketplace typically adds a handful of locally-written reviews. Empty = only the product's own marketplace.",
            "items": {
              "type": "string",
              "enum": [
                "amazon.com",
                "amazon.co.uk",
                "amazon.de",
                "amazon.fr",
                "amazon.it",
                "amazon.es",
                "amazon.ca",
                "amazon.com.au",
                "amazon.co.jp",
                "amazon.in",
                "amazon.com.br",
                "amazon.com.mx",
                "amazon.nl",
                "amazon.sg",
                "amazon.ae",
                "amazon.sa",
                "amazon.pl",
                "amazon.se",
                "amazon.com.tr"
              ],
              "enumTitles": [
                "United States (amazon.com)",
                "United Kingdom (amazon.co.uk)",
                "Germany (amazon.de)",
                "France (amazon.fr)",
                "Italy (amazon.it)",
                "Spain (amazon.es)",
                "Canada (amazon.ca)",
                "Australia (amazon.com.au)",
                "Japan (amazon.co.jp)",
                "India (amazon.in)",
                "Brazil (amazon.com.br)",
                "Mexico (amazon.com.mx)",
                "Netherlands (amazon.nl)",
                "Singapore (amazon.sg)",
                "UAE (amazon.ae)",
                "Saudi Arabia (amazon.sa)",
                "Poland (amazon.pl)",
                "Sweden (amazon.se)",
                "Turkey (amazon.com.tr)"
              ]
            },
            "default": []
          },
          "includeAggregates": {
            "title": "Include Review Aggregates",
            "type": "boolean",
            "description": "Emit one additional `amazon_review_aggregate` record per product with the product title, average rating, global ratings count, star histogram (plus derived per-star counts), and \"Customers say\" AI summary with aspects -- 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.",
            "default": true
          },
          "country": {
            "title": "Amazon Domain",
            "enum": [
              "amazon.com",
              "amazon.co.uk",
              "amazon.de",
              "amazon.fr",
              "amazon.it",
              "amazon.es",
              "amazon.ca",
              "amazon.com.au",
              "amazon.co.jp",
              "amazon.in",
              "amazon.com.br",
              "amazon.com.mx",
              "amazon.nl",
              "amazon.sg",
              "amazon.ae",
              "amazon.sa",
              "amazon.pl",
              "amazon.se",
              "amazon.com.tr"
            ],
            "type": "string",
            "description": "Amazon country domain to scrape from. URLs from a different domain are honored automatically.",
            "default": "amazon.com"
          },
          "maxReviews": {
            "title": "Max Reviews per Product",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Hard cap on the number of reviews returned per product AFTER merging and deduplication (1-2000). The product-page sample alone yields ~8-13; the extended review feed can add 100-850+ for popular US products.",
            "default": 100
          },
          "sortBy": {
            "title": "Sort Reviews By",
            "enum": [
              "helpful",
              "recent"
            ],
            "type": "string",
            "description": "How to sort the returned reviews: most helpful first, or most recent first.",
            "default": "helpful"
          },
          "filterByStar": {
            "title": "Filter by Star Rating",
            "enum": [
              "",
              "1",
              "2",
              "3",
              "4",
              "5",
              "positive",
              "critical"
            ],
            "type": "string",
            "description": "Keep only reviews with this rating. `positive` keeps 4-5 star reviews; `critical` keeps 1-2 star reviews. Applied to the merged set, so narrow filters can legitimately return few or no rows.",
            "default": ""
          },
          "verifiedPurchasesOnly": {
            "title": "Verified Purchases Only",
            "type": "boolean",
            "description": "Keep only reviews carrying Amazon's Verified Purchase badge. Applied server-side for the extended feed and client-side for product-page rows.",
            "default": false
          },
          "filterKeywords": {
            "title": "Filter by Keywords",
            "type": "array",
            "description": "Keep only reviews whose title or text contains at least one of these keywords (case-insensitive). Empty = no keyword filter.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "reviewsNewerThan": {
            "title": "Reviews Newer Than",
            "type": "string",
            "description": "Keep only reviews dated on or after this date (e.g. 2026-01-15 or any ISO date). Reviews whose localized date cannot be parsed are kept. Empty = no date filter."
          },
          "mediaReviewsOnly": {
            "title": "Media Reviews Only",
            "type": "boolean",
            "description": "Keep only reviews that include at least one reviewer-uploaded image or video.",
            "default": false
          },
          "includeImages": {
            "title": "Include Review Images",
            "type": "boolean",
            "description": "Extract images and videos uploaded by reviewers (full-resolution URLs).",
            "default": true
          },
          "includeGdprSensitive": {
            "title": "Include GDPR Sensitive Data",
            "type": "boolean",
            "description": "Include reviewer names, profile links, and avatars. Set to false for GDPR compliance.",
            "default": false
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}