{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Reviews Scraper",
    "description": "Extract customer reviews from any Amazon product with filtering by star rating, verified purchases, and sorting options. Returns structured data including review text, ratings, helpful counts, dates, sentiment hints, images, and more across 19+ Amazon domains.",
    "version": "1.1",
    "x-build-id": "qUjsc124KEz9qEdwF"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/crawlerbros~amazon-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-crawlerbros-amazon-reviews-scraper",
        "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/crawlerbros~amazon-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-crawlerbros-amazon-reviews-scraper",
        "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/crawlerbros~amazon-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-crawlerbros-amazon-reviews-scraper",
        "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",
        "required": [
          "productUrls",
          "proxyConfiguration"
        ],
        "properties": {
          "productUrls": {
            "title": "Product URLs",
            "type": "array",
            "description": "List of Amazon product URLs to scrape reviews from. Supports /dp/, /gp/product/, and /product/ URL formats across 19+ Amazon domains.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Keyword Search (discovery, optional)",
            "type": "array",
            "description": "Optional. Search terms — the actor discovers matching products on `country` and scrapes reviews for up to `maxProductsFromDiscovery` of them, in addition to any `productUrls`.",
            "items": {
              "type": "string"
            }
          },
          "categoryUrls": {
            "title": "Category URLs (discovery, optional)",
            "type": "array",
            "description": "Optional. Amazon category/browse-node URLs to discover products from, in addition to any `productUrls`/`keywords`.",
            "items": {
              "type": "string"
            }
          },
          "maxProductsFromDiscovery": {
            "title": "Max Products from Discovery",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of products to discover per `keywords`/`categoryUrls` entry.",
            "default": 5
          },
          "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",
              "amazon.ie",
              "amazon.com.be",
              "amazon.co.za",
              "amazon.eg"
            ],
            "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": 15,
            "type": "integer",
            "description": "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.",
            "default": 15
          },
          "sortBy": {
            "title": "Sort Reviews By",
            "enum": [
              "helpful",
              "recent"
            ],
            "type": "string",
            "description": "How to sort the reviews",
            "default": "helpful"
          },
          "filterByStar": {
            "title": "Filter by Star Rating",
            "enum": [
              "",
              "1",
              "2",
              "3",
              "4",
              "5"
            ],
            "type": "string",
            "description": "Filter reviews by specific star rating (1-5). Leave empty for all ratings.",
            "default": ""
          },
          "verifiedPurchasesOnly": {
            "title": "Verified Purchases Only",
            "type": "boolean",
            "description": "Cookie mode only (requires `cookieString`) — restrict to Verified Purchase reviews. Has no effect in cookie-free mode. `reviewerType` wins over this field when both are set.",
            "default": false
          },
          "reviewerType": {
            "title": "Reviewer Type (cookie mode only)",
            "enum": [
              "",
              "all_reviews",
              "avp_only_reviews"
            ],
            "type": "string",
            "description": "Cookie mode only (requires `cookieString`) — Amazon's own reviewer-type filter. Has no effect in cookie-free mode.",
            "default": ""
          },
          "includeImages": {
            "title": "Include Review Images",
            "type": "boolean",
            "description": "Extract images uploaded by reviewers",
            "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
          },
          "includeAggregates": {
            "title": "Include Product Rating Aggregates",
            "type": "boolean",
            "description": "Push a distinct `amazon_review_aggregate` record per product with averageRating/globalRatingsCount/starsBreakdown/customersSay, parsed from the same page (no extra request). Populated even when individual reviews are unavailable (walled).",
            "default": true
          },
          "sourceMode": {
            "title": "Source Mode",
            "enum": [
              "AUTO",
              "INLINE_ONLY"
            ],
            "type": "string",
            "description": "AUTO (default): try the requested `country` first with the cheaper AUTO/datacenter proxy, then automatically fall back to other marketplaces (`countryFallback`) and escalate once to a forced RESIDENTIAL proxy if a sign-in wall/block is actually detected. INLINE_ONLY: strict, cheapest, single-marketplace mode -- disables BOTH multi-marketplace fallback and RESIDENTIAL escalation, even if `countryFallback` is enabled or blocked. Has no effect on cookie mode (`cookieString`).",
            "default": "AUTO"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "REQUIRED. AUTO (datacenter) is tried first by default -- cheaper, and usually sufficient. The actor automatically escalates to a forced RESIDENTIAL proxy only when a sign-in wall/block is actually detected on a marketplace attempt (skipped when `sourceMode` is `INLINE_ONLY`, or when you pin RESIDENTIAL here yourself).",
            "default": {
              "useApifyProxy": true
            }
          },
          "countryFallback": {
            "title": "Multi-marketplace Fallback",
            "type": "boolean",
            "description": "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, or when `sourceMode` is `INLINE_ONLY` (always disabled there regardless of this value). Disable for strict single-marketplace matching.",
            "default": true
          },
          "cookieString": {
            "title": "Amazon Session Cookie String (optional)",
            "type": "string",
            "description": "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.",
            "default": ""
          },
          "cookieModeMaxReviews": {
            "title": "Max Reviews per Product (cookie mode)",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "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.",
            "default": 500
          },
          "maxConcurrency": {
            "title": "Max Concurrency",
            "minimum": 1,
            "maximum": 5,
            "type": "integer",
            "description": "Maximum number of concurrent browser pages",
            "default": 1
          },
          "requestTimeout": {
            "title": "Request Timeout (seconds)",
            "minimum": 30,
            "maximum": 180,
            "type": "integer",
            "description": "Timeout for each page request in seconds",
            "default": 60
          },
          "retryCount": {
            "title": "Retry Count",
            "minimum": 1,
            "maximum": 10,
            "type": "integer",
            "description": "Number of retries for failed requests / blocked sessions",
            "default": 3
          }
        }
      },
      "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}