{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Reviews Scraper & API — Product Reviews, Ratings",
    "description": "Scrape AliExpress product reviews by URL or item id: star rating, buyer feedback translated into 16 languages, buyer photos, country, SKU variant. Date, keyword and star filters, new-review monitoring, free sentiment analysis. For dropshipping product research. No login. API and MCP ready.",
    "version": "1.17",
    "x-build-id": "UL15jwf4pjgWfGhg9"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/kestrel~aliexpress-reviews-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-kestrel-aliexpress-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/kestrel~aliexpress-reviews-scraper/runs": {
      "post": {
        "operationId": "runs-sync-kestrel-aliexpress-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/kestrel~aliexpress-reviews-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-kestrel-aliexpress-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",
        "properties": {
          "productUrls": {
            "title": "AliExpress product URLs",
            "uniqueItems": true,
            "type": "array",
            "description": "AliExpress product pages, e.g. https://www.aliexpress.com/item/1005006255429323.html. aliexpress.us and .ru, /i/<id>.html, tracking junk after the ?, links copied without https://, bare item ids, app share links (https://a.aliexpress.com/_mKyJbQW) and affiliate links (https://s.click.aliexpress.com/e/_DmXyz) all work. An entry that is no AliExpress product, search, category or store link becomes a free invalid_target row, and the rest of the list is read.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "productIds": {
            "title": "AliExpress item ids",
            "uniqueItems": true,
            "type": "array",
            "description": "AliExpress numeric item ids, e.g. 1005006255429323 — the number in /item/<id>.html, and what an earlier run's product_id gives you. All three AliExpress id namespaces work (1005…, 3256… on aliexpress.us, and the legacy 2255…/4000… ids), and they resolve to the same reviews.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (same as product URLs)",
            "type": "array",
            "description": "An alias for AliExpress product URLs, for integrations, templates and tools that always send startUrls: Make, n8n, Zapier, a Google Sheet of links, or another scraper's output. Entries can be URL strings, item ids, share links, {\"url\": …} objects, search or category URLs (their products are found first), store URLs, or {\"requestsFromUrl\": \"https://…/links.txt\"}: a text, CSV or sheet export with one of those per line. A product named twice is still read once.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "searchQueries": {
            "title": "Search phrases (find products, then their reviews)",
            "uniqueItems": true,
            "type": "array",
            "description": "AliExpress search phrases, e.g. \"wireless earbuds\", \"ceramic mug\". Each phrase finds its first maxProductsPerSearch products (best-selling first by default) and the actor delivers their reviews in the same run, billed per review as usual: the search itself is free. A search or category URL pasted into productUrls or startUrls works the same way. Rows carry target = the phrase and search_rank = the product's position.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "storeUrls": {
            "title": "Store URLs (a store's products, then their reviews)",
            "uniqueItems": true,
            "type": "array",
            "description": "AliExpress store pages, e.g. https://www.aliexpress.com/store/1100398072, or bare store numbers: each gives its first maxProductsPerSearch products and the actor delivers their reviews. AliExpress answers store lists only inside a real browser, which the run installs (about 20 s); left at the default memory the run starts with 4096 MB for it. With memory set below 2048 MB, or if AliExpress's slider meets 4 browser visits (never solved), the store is a free row saying why.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "maxProductsPerSearch": {
            "title": "Products per search phrase, store or photo",
            "minimum": 1,
            "maximum": 200,
            "type": "number",
            "description": "How many products each search phrase, store and photo contributes (1-200, default 5). Each product then gets up to maxReviewsPerProduct reviews, so 5 products x 100 reviews is at most 500 billed reviews per phrase. Ignored without searchQueries, storeUrls or imageUrls.",
            "default": 5
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": -1,
            "maximum": 50000,
            "type": "number",
            "description": "0 (or -1) = every review AliExpress serves of the product: at most 5,000 on a best-seller (its limit on one list; completeHistory reads past it). N = at most N per product: with no filter on, the first N AliExpress serves (newest first when sort is newest); with any filter or onlyNewReviews on, N counts the reviews DELIVERED, read on until N pass. A product never bills more than N reviews. Default 100.",
            "default": 100
          },
          "completeHistory": {
            "title": "Complete history: read past AliExpress's 5,000-review limit",
            "type": "boolean",
            "description": "AliExpress serves at most 5,000 reviews of any one list, so on a best-seller scrapers stop at 5,000. true = when a product lists more, also read its other lists of the same reviews (other order, each star, photos, follow-ups, each buyer country), deduplicated: 21,967 of 22,005 and 16,627 of 16,729 in our runs. Billed per review as usual; maxReviewsPerProduct still caps it (0 = all). Not used by onlyNewReviews or sort oldest with a cap. Default false: one list.",
            "default": false
          },
          "reviewsFilter": {
            "title": "Server-side review filter",
            "type": "string",
            "description": "\"all\" (default) = no filter. \"with_photos\" = only reviews with buyer photos. \"with_follow_up\" = only buyers who came back weeks later to update their review, the best durability signal. \"same_country\" = only buyers from the one country in countries (exactly one entry there). These are the filters AliExpress itself applies: pages you do not want are never fetched or billed. Other scrapers' spellings (image, withPhotos, additional, local…) are accepted.",
            "default": "all"
          },
          "minRating": {
            "title": "Only reviews at or above this star rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "AliExpress reviews are whole stars, 1 to 5. 0 = no floor; 5 keeps only the perfect scores (4.5 counts as 5). Runs before billing: filtered reviews are never charged, and maxReviewsPerProduct then counts the reviews that pass.",
            "default": 0
          },
          "maxRating": {
            "title": "Only reviews at or below this star rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "The other end of the same 1-5 scale: 0 = no ceiling, 2 gives a complaints feed of 1-2 star reviews (2.5 counts as 2). Combine with sort lowest_rating and the Complaints view. Filtered reviews are never charged; maxReviewsPerProduct counts the reviews that pass.",
            "default": 0
          },
          "sinceDate": {
            "title": "Only reviews since",
            "type": "string",
            "description": "Keep only reviews written on or after this date: \"2026-06-01\" (YYYY-MM-DD) or a look-back window: \"30 days\", \"2 weeks\", \"6 months\", \"1 year\". Empty (default) = no date limit. The actor reads AliExpress's newest-first order and stops at the first review older than the date, so a short window is fast and only the reviews in it are charged; maxReviewsPerProduct then counts the reviews delivered.",
            "default": ""
          },
          "requireText": {
            "title": "Only reviews with a written text",
            "type": "boolean",
            "description": "true = drop star-only reviews (an empty feedback field) before billing: on AliExpress roughly one review in five is a bare star rating, so this is a real saving when you are after review text for product research or sentiment analysis. false (default) = keep them, with text empty.",
            "default": false
          },
          "keywords": {
            "title": "Only reviews mentioning",
            "uniqueItems": true,
            "type": "array",
            "description": "Keep only reviews that mention at least one of these words or phrases, e.g. battery, broke, fake, refund, size, customs. Matching ignores case and looks at the buyer's original text, the translation and the follow-up review, so an English keyword finds a review written in Portuguese once it is translated. Empty = no keyword filter. Runs before billing: a review that mentions none of them is never charged.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "title": "Buyer countries",
            "uniqueItems": true,
            "type": "array",
            "description": "Keep only reviews from buyers in these ISO-2 countries, e.g. US, BR, ES, PL. Empty = every country. The first entry also tells AliExpress which market to answer as, which decides the ordering it serves and which reviews the \"Only buyers from the chosen country\" filter keeps. Filtered reviews are never charged.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "sort": {
            "title": "Review order",
            "type": "string",
            "description": "The order the reviews are delivered in. \"newest\" uses AliExpress's own newest-first order (\"Sort by latest\"), so a capped run gets the actual newest reviews. \"oldest\", \"lowest_rating\" and \"highest_rating\" order the reviews the run collected. Other scrapers' spellings (latest, rating_desc…) are accepted.",
            "default": "default"
          },
          "language": {
            "title": "Translation language",
            "type": "string",
            "description": "Language of text_translated: \"en_US\" (default), \"es_ES\", \"pt_BR\", \"fr_FR\", \"de_DE\", \"it_IT\", \"nl_NL\", \"pl_PL\", \"tr_TR\", \"ru_RU\", \"ja_JP\", \"ko_KR\", \"ar_MA\", \"he_IL\", \"id_ID\", \"th_TH\" (the site's iw_IL and in_ID work too). AliExpress machine-translates every review into it; text keeps the original. Keep \"en_US\" when analyzeReviews is on. A cold page answering with translations missing is re-asked once and filled in, never charged twice.",
            "default": "en_US"
          },
          "onlyNewReviews": {
            "title": "Only new reviews (monitoring mode)",
            "type": "boolean",
            "description": "true = monitoring mode for a schedule: each run delivers and bills only reviews no earlier run delivered. It reads AliExpress's newest-first order and stops two weeks below the newest review seen last time, so a daily run is a few requests. The first run is the baseline: the newest maxReviewsPerProduct reviews (0 = all); older history is never billed later as new. A review your spending limit refused returns next run. false (default) = every run delivers every matching review.",
            "default": false
          },
          "includeProductDetails": {
            "title": "Product details (price, stock, shipping, store) — add-on",
            "type": "boolean",
            "description": "true = one extra row per product (type details), billed as one product_details event: price range, discount, sold count, stock, image, new-shopper flag and buy limit of every variant, shipping to shipTo, the store and its seller rating, specifications, category path, description text and photos. Only for products that delivered reviews. Needs a browser the run installs (the default memory becomes 2048 MB); memory set below that, or not sold to shipTo: a free note, no charge.",
            "default": false
          },
          "analyzeReviews": {
            "title": "Analyze reviews (sentiment, topics, insights)",
            "type": "boolean",
            "description": "true = free review analysis: each review row gains sentiment (positive / neutral / negative), a -1 to 1 sentiment_score, topics (quality, delivery, size and fit, value, durability, seller service…) and rating_text_mismatch (4-5 star reviews that read as complaints); each product gets a free insights row: sentiment split, top complaints and praise, ratings by SKU variant, country and month. Keep language \"en_US\": it reads English. No AI model, no extra charge. false (default) = no extra columns.",
            "default": false
          },
          "includeProductRow": {
            "title": "Add a product row (rating breakdown, free)",
            "type": "boolean",
            "description": "One free row per product: title, image, average rating, the 1-5 star histogram, the positive/neutral/negative split, how many reviews carry photos or a follow-up, and the attributes buyers rated. One extra request per product, never charged. On by default for API and agent calls; the Console form starts with it off, so the Output tab and its CSV export hold one row per review: tick it for the rating breakdown.",
            "default": true
          },
          "statusRows": {
            "title": "Status rows (one per product: what happened)",
            "enum": [
              "all",
              "problems",
              "none"
            ],
            "type": "string",
            "description": "all (the API default) = one free type=status row per product or search: delivered, filtered, not found, refused and why. problems = only targets that failed, were skipped or carry a note (the Console form starts here, so a run where every product worked exports one row per review). none = no status rows (with includeProductRow off, the export holds only reviews). SUMMARY and the status message always say what was left out.",
            "default": "all"
          },
          "reviewTopics": {
            "title": "Only reviews on AliExpress's own topics",
            "uniqueItems": true,
            "type": "array",
            "description": "Keep only reviews AliExpress itself filed under one of these topics, read through its own topic filter: the names in the product row's review_topics, e.g. \"defective\", \"good sound\", \"fast delivery\". A product without that topic gets none (a note on its status row). Unlike keywords, which search the text, this is AliExpress's classification. Empty (default) = no topic filter.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "imageUrls": {
            "title": "Photos to find products by (search by image)",
            "uniqueItems": true,
            "type": "array",
            "description": "Image URLs (JPEG, PNG, GIF or WebP, up to 5 MB; a data: URL works too): each goes to AliExpress's own search by image and its first maxProductsPerSearch matches, best match first, then deliver their reviews. Finding them is free. The photo is uploaded by a real browser page the run installs (about 20 s); left at the default memory the run starts with 4096 MB for it. With memory set below 2048 MB, a free row says why.",
            "default": [],
            "items": {
              "type": "string"
            }
          },
          "searchSort": {
            "title": "Which products a search or store gives first",
            "type": "string",
            "description": "\"orders\" (default) = best-selling first: the products with the most buyers, and so the most reviews. \"relevance\" = AliExpress's best match, \"newest\" = newest listings, \"price_asc\" / \"price_desc\" = by price. Applies to searchQueries (a pasted search or category URL keeps its own order), storeUrls and imageUrls (a photo's matches come best match first unless another order than orders is set).",
            "default": "orders"
          },
          "shipFrom": {
            "title": "Ships from (search filter)",
            "type": "string",
            "description": "Two-letter country the found products ship from, e.g. US, ES, FR, DE: AliExpress's own \"Shipping from\" filter on searchQueries and pasted search or category URLs. Empty (default) = any country. Not applied to productUrls, productIds or storeUrls."
          },
          "minPrice": {
            "title": "Lowest price (search filter)",
            "minimum": 0,
            "type": "number",
            "description": "Only products found by a search at or above this price, in the store currency AliExpress shows (USD from the actor). Empty = no floor."
          },
          "maxPrice": {
            "title": "Highest price (search filter)",
            "minimum": 0,
            "type": "number",
            "description": "Only products found by a search at or below this price. Empty = no ceiling."
          },
          "hideBuyerDetails": {
            "title": "Hide buyer details",
            "type": "boolean",
            "description": "true = blank the buyer's display name, avatar and gender in every review row (the columns stay, the values are empty); the buyer's country, the review text, photos and everything else are unchanged. For teams whose data policy does not allow storing reviewer identity, or a dataset going into an LLM or a shared sentiment pipeline. false (default) = buyer details as AliExpress shows them.",
            "default": false
          },
          "stateStoreName": {
            "title": "Monitoring memory (key-value store name)",
            "type": "string",
            "description": "The named key-value store in your own Apify account where onlyNewReviews remembers what it delivered, one small record per product. Default \"aliexpress-reviews-seen\". Give each independent monitor its own name (3-63 letters, digits and hyphens); delete the store to start again from a fresh baseline. Ignored when onlyNewReviews is off.",
            "default": "aliexpress-reviews-seen"
          },
          "shipTo": {
            "title": "Ship-to country for product details",
            "type": "string",
            "description": "Two-letter country of the market: search and store listings (which products are found, listing_price and listing_currency) and the details' shipping options, cost and delivery days are for this country, e.g. US, DE, GB, BR. Set through AliExpress's own Ship-to preference and shipping panel. Default US.",
            "default": "US"
          },
          "currency": {
            "title": "Currency for product details",
            "type": "string",
            "description": "Three-letter currency of listing_price on found products and of the details' prices, e.g. USD, EUR, GBP, BRL. Default USD. SUMMARY.listing_currencies counts what AliExpress actually showed, and the run says so if it is not this one.",
            "default": "USD"
          },
          "sessions": {
            "title": "Parallel sessions",
            "minimum": 1,
            "maximum": 16,
            "type": "number",
            "description": "Proxy sessions (egress IPs) fetching pages in parallel, e.g. 2 (default). More is faster; each is paced separately. Raise it for a long product list.",
            "default": 2
          },
          "perIp": {
            "title": "Requests per second per session",
            "minimum": 0.1,
            "maximum": 5,
            "type": "number",
            "description": "Pace for each session. AliExpress's feedback endpoint answered 150 back-to-back requests from a single datacenter IP with no throttling at all, and 10 of 10 at 1 req/s; 1-2 is comfortable.",
            "default": 1
          },
          "proxyConfiguration": {
            "title": "Proxy",
            "type": "object",
            "description": "Apify Proxy with the datacenter group is enough: the feedback endpoint answers plain HTTP requests from datacenter ranges with no key, no cookies and no bot gate. Residential works too and costs more. Keep the default.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}