{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Customer Review & Rating Summary Scraper",
    "description": "Get Amazon customer reviews and a product-level rating summary by product URL, keyword, or category, with star-rating and sort filters, across 23 Amazon domains.",
    "version": "1.0",
    "x-build-id": "Uz8bhFkvsoBLw91SC"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/vexaloom-labs~amazon-customer-review-and-rating-summary-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-vexaloom-labs-amazon-customer-review-and-rating-summary-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/vexaloom-labs~amazon-customer-review-and-rating-summary-scraper/runs": {
      "post": {
        "operationId": "runs-sync-vexaloom-labs-amazon-customer-review-and-rating-summary-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/vexaloom-labs~amazon-customer-review-and-rating-summary-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-vexaloom-labs-amazon-customer-review-and-rating-summary-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": {
          "productUrls": {
            "title": "Product URLs or ASINs",
            "type": "array",
            "description": "Amazon product URLs (/dp/, /gp/product/, /gp/aw/d/, /product/) or bare 10-character ASINs, on any supported Amazon domain. Leave empty to discover products from `keywords`/`categoryUrls` instead.",
            "items": {
              "type": "string"
            }
          },
          "keywords": {
            "title": "Keywords (discover products)",
            "type": "array",
            "description": "Search terms used to discover products when `productUrls` is empty (e.g. \"wireless earbuds\"). Each keyword contributes up to `maxProductsToDiscover` products.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "categoryUrls": {
            "title": "Category or Search URLs (discover products)",
            "type": "array",
            "description": "Advanced discovery: Amazon `/s?...` search URLs or `/b?node=...` category URLs. Used only when `productUrls` is empty.",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "maxProductsToDiscover": {
            "title": "Max Products to Discover",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum products discovered from each keyword or category URL (1-50). Ignored when `productUrls` is supplied.",
            "default": 5
          },
          "country": {
            "title": "Amazon Marketplace",
            "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 storefront to use for bare ASINs, discovery, and products whose URL does not carry a domain. Product URLs keep their own domain.",
            "default": "amazon.com"
          },
          "maxReviews": {
            "title": "Max Reviews per Product",
            "minimum": 1,
            "maximum": 2000,
            "type": "integer",
            "description": "Hard cap per product after merging and deduplication (1-2000). The product-page sample alone yields about 8-13 rows; the optional extended feed can add 100-800+ for popular US products. In optional cookie mode this is the paginated cap.",
            "default": 100
          },
          "extendedHistory": {
            "title": "Extended Review History",
            "type": "boolean",
            "description": "Merge Amazon's public extended review feed for each ASIN (no login): up to 100 rows per star/sort bucket, typically 100-800+ unique reviews for popular US products, deduplicated against the product-page sample. Coverage varies by ASIN and the feed carries Amazon.com reviews only.",
            "default": true
          },
          "mergeMarketplaces": {
            "title": "Merge Extra Marketplaces",
            "type": "array",
            "description": "Fetch the same product on these additional Amazon marketplaces and merge their deduplicated product-page reviews. Empty = the product's own marketplace only.",
            "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",
                "amazon.ie",
                "amazon.com.be",
                "amazon.co.za",
                "amazon.eg"
              ],
              "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)",
                "United Arab Emirates (amazon.ae)",
                "Saudi Arabia (amazon.sa)",
                "Poland (amazon.pl)",
                "Sweden (amazon.se)",
                "Turkey (amazon.com.tr)",
                "Ireland (amazon.ie)",
                "Belgium (amazon.com.be)",
                "South Africa (amazon.co.za)",
                "Egypt (amazon.eg)"
              ]
            },
            "default": []
          },
          "sortBy": {
            "title": "Sort Reviews By",
            "enum": [
              "helpful",
              "recent"
            ],
            "type": "string",
            "description": "Order of 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 stars and `critical` keeps 1-2 stars. Applied after merging, 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 in the extended feed (and cookie mode) 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 (YYYY-MM-DD or any ISO date). Reviews whose localized date cannot be parsed are kept. Empty = no date filter.",
            "default": ""
          },
          "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 and Videos",
            "type": "boolean",
            "description": "Extract full-resolution image and video URLs uploaded by reviewers.",
            "default": true
          },
          "includeAggregates": {
            "title": "Include Rating Summary",
            "type": "boolean",
            "description": "Emit one `amazon_review_aggregate` record per product with product title, average rating, global ratings count, star histogram, derived per-star counts, and Amazon's \"Customers say\" summary with aspects. The histogram is filled from the rating-summary popover when the page omits it.",
            "default": true
          },
          "includeGdprSensitive": {
            "title": "Include Reviewer Names and Profiles",
            "type": "boolean",
            "description": "Include reviewer display name, profile link, and avatar. Leave off for GDPR-sensitive workloads.",
            "default": false
          },
          "cookieString": {
            "title": "Amazon Session Cookie (optional)",
            "type": "string",
            "description": "Optional. Paste your own logged-in Amazon session cookie (the literal Cookie header value) to use paginated /product-reviews/ and unlock deeper history. Never required; the actor returns real public data without it. Never paste a password."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}