{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Product Reviews Scraper — ASIN Text & Stars",
    "description": "Amazon products + reviews with star/date/keyword filters. includeProductSummary rating histogram; PPE product-summary from 2026-09-19. Soft CTA → Amazon Product Scanner / Skip Trace.",
    "version": "3.1",
    "x-build-id": "3fEInzlsx9lDT1nzm"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/intelscrape~amazon-product-review-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-intelscrape-amazon-product-review-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/intelscrape~amazon-product-review-scraper/runs": {
      "post": {
        "operationId": "runs-sync-intelscrape-amazon-product-review-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/intelscrape~amazon-product-review-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-intelscrape-amazon-product-review-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",
        "properties": {
          "startUrls": {
            "title": "Product URLs",
            "type": "array",
            "description": "Product URLs or bare ASINs. Accepts {url} objects or plain strings (including /dp/, /gp/product/, /gp/aw/d/, asin= query, /product/, or bare 10-char ASINs). Limited: bare product URLs are blocked by Amazon and are resolved via search. Returns nothing (and charges nothing) when the product is not found. Use keywords for reliable volume. If nothing is found, the run hard-fails (no silent empty SUCCEEDED).",
            "items": {
              "type": "object"
            },
            "default": []
          },
          "keywords": {
            "title": "Search keywords",
            "type": "array",
            "description": "Recommended. Keyword search is the most reliable way to pull products at volume.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "asinList": {
            "title": "Direct ASINs",
            "type": "array",
            "description": "Limited: Amazon blocks direct product-page lookups, so an ASIN is resolved via search and may not be found. Returns nothing (and charges nothing) when it is not. Use keywords for reliable volume. If nothing is found, the run hard-fails (no silent empty SUCCEEDED).",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "countryCode": {
            "title": "Amazon marketplace",
            "enum": [
              "US",
              "UK",
              "GB",
              "DE",
              "CA",
              "FR",
              "ES",
              "IT",
              "JP",
              "AU",
              "MX",
              "SG",
              "IN",
              "BR",
              "AE",
              "NL",
              "BE",
              "PL",
              "SE",
              "TR",
              "SA",
              "EG",
              "IE"
            ],
            "type": "string",
            "description": "Which Amazon marketplace to scrape. UK and GB both use amazon.co.uk. Expanded TLDs: SG, IN, BR, AE, NL, BE, PL, SE, TR, SA, EG, IE (plus classic US/UK/DE/CA/FR/ES/IT/JP/AU/MX).",
            "default": "US"
          },
          "scrapeReviews": {
            "title": "Scrape reviews",
            "type": "boolean",
            "description": "Collect customer reviews for each scraped product: star rating, verified badge, date, title, and full review body. PPE event apify-default-dataset-item is charged per review row. Pair with maxReviewPages and sortReviewsBy to control volume.",
            "default": false
          },
          "maxReviewPages": {
            "title": "Review pages per product",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum review pages to fetch per product per star/keyword filter combination.",
            "default": 10
          },
          "maxReviews": {
            "title": "Max total reviews (count stop)",
            "minimum": 1,
            "type": "integer",
            "description": "Stop collecting reviews once this total is reached across all products. Leave blank for no limit. Works alongside maxReviewPages."
          },
          "sortReviewsBy": {
            "title": "Sort reviews by",
            "enum": [
              "recent",
              "helpful"
            ],
            "type": "string",
            "description": "Order in which Amazon review pages are fetched. recent = newest first; helpful = most-voted first.",
            "default": "recent"
          },
          "filterByRatings": {
            "title": "Filter reviews by star rating",
            "type": "array",
            "description": "Only fetch reviews with the listed star ratings (1-5). Use \"critical\" for all 1-2 star reviews combined.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "reviewsFilterByKeywords": {
            "title": "Search keywords within reviews",
            "type": "array",
            "description": "Amazon keyword filter applied within reviews. Only reviews matching these terms are fetched per product.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "reviewsCutoffDate": {
            "title": "Reviews newer than (cutoff date)",
            "type": "string",
            "description": "Only keep reviews newer than this date (YYYY-MM-DD). When set, Store PPE event date-filter ($0.001) is charged once per run (junglee parity)."
          },
          "includeOtherCountriesReviews": {
            "title": "Include international reviews",
            "type": "boolean",
            "description": "Include reviews posted from international marketplaces (e.g. UK/DE shoppers reviewing on amazon.com).",
            "default": false
          },
          "scrapeProductDetails": {
            "title": "Scrape product details",
            "type": "boolean",
            "description": "Extract full product data (price, BSR, images, features, seller info) alongside reviews. Disable for review-only scraping.",
            "default": true
          },
          "maxProductsPerKeyword": {
            "title": "Max products per keyword",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum number of products to scrape per search keyword.",
            "default": 20
          },
          "minRating": {
            "title": "Minimum product rating filter",
            "minimum": 1,
            "maximum": 5,
            "type": "number",
            "description": "Only return products with this average star rating or higher (applies to product search, not reviews)."
          },
          "minPrice": {
            "title": "Minimum price $ (optional)",
            "type": "number",
            "description": "Only return products priced at or above this value."
          },
          "maxPrice": {
            "title": "Maximum price $ (optional)",
            "type": "number",
            "description": "Only return products priced at or below this value."
          },
          "onlyInStock": {
            "title": "In-stock items only",
            "type": "boolean",
            "description": "Filter to only include products currently in stock.",
            "default": false
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Residential proxies are required for Amazon. Datacenter IPs are blocked and return zero results.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          },
          "demoMode": {
            "title": "Demo mode",
            "type": "boolean",
            "description": "Push 2 fictional sample items (product + review) without hitting Amazon. Use for Store try-outs. Live empty runs hard-fail.",
            "default": false
          },
          "onlyVerifiedPurchases": {
            "title": "Only Verified Purchase reviews",
            "type": "boolean",
            "description": "When true, keep only reviews that carry Amazon's Verified Purchase badge. Non-verified reviews are dropped before push.",
            "default": true
          },
          "includeProductSummary": {
            "title": "Include product summary (rating histogram) — paid after 2026-10-05",
            "type": "boolean",
            "description": "When true, attaches productSummary (averageRating / totalRatings / starHistogram) on each product row. Bills PPE event product-summary ($0.005) once per product with a summary after Store start 2026-10-05; until then the enrichment is delivered free (charge gated in code).",
            "default": true
          },
          "onlyChargeNewReviews": {
            "title": "Flag reviews already returned in a previous run",
            "type": "boolean",
            "description": "When true, remember review IDs in a named Key-Value store across runs. Duplicate reviews are still returned but marked alreadyPaidForInPreviousRun=true. Billing uses the existing apify-default-dataset-item event on every default-dataset row (including flagged duplicates) — filter client-side on the flag to avoid re-paying for sync jobs. No new PPE event names.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}