{ "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.1", "x-build-id": "q8BX2G7xjOFLNwzYu" }, "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, aliexpress.ru, the /i/.html short form and any share link with tracking junk after the ? all work, because every AliExpress item URL carries the numeric item id in its path. No page has to be loaded to resolve them. A bare item id pasted here works too.", "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/.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 the output of an AliExpress product scraper. Every entry is an AliExpress product URL; they are merged with the two lists above and a product named twice is still read once.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 0, "maximum": 50000, "type": "integer", "description": "0 = every review the product has (AliExpress pages them in blocks of up to 500; a best-seller runs to a few thousand). N = the first N AliExpress serves. This is the main cost control: it caps how many reviews are read, and the filters below then decide which of them are worth paying for.", "default": 100 }, "reviewsFilter": { "title": "Server-side review filter", "enum": [ "all", "with_photos", "with_follow_up", "same_country" ], "type": "string", "description": "The only three filters AliExpress itself applies, so the pages you do not want are never even fetched. All reviews = no filter. Only reviews with photos = AliExpress's own photo filter (buyer photos are the fastest way to judge whether a product is worth listing). Only reviews with a follow-up = buyers who came back weeks later to update their review, the best durability signal on the site. Only buyers from the chosen country = AliExpress's one country filter; it needs exactly one entry in Buyer countries.", "default": "all" }, "minRating": { "title": "Only reviews at or above this star rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "AliExpress reviews are whole stars, 1 to 5. 0 = no floor; 5 keeps only the perfect scores. AliExpress has no server-side star filter, so this one runs in the actor — the pages are still read, the filtered reviews are simply never charged.", "default": 0 }, "maxRating": { "title": "Only reviews at or below this star rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "The other end of the same 1-5 scale: 0 = no ceiling, 3 gives a complaints feed of everything a buyer was unhappy about. Combine with Sort = lowest rated first and the Complaints view in the dataset tab. Filtered reviews are never charged.", "default": 0 }, "sinceDate": { "title": "Only reviews since", "type": "string", "description": "Keep only reviews written on or after this date: YYYY-MM-DD, or a look-back window such as 30 days, 2 weeks, 6 months or 1 year. Empty = no date limit. It is what a weekly or monthly AliExpress review monitoring schedule needs, and it answers the question a supplier check really asks — what are buyers saying about the batch that is shipping now, not the one from two years ago. AliExpress cannot sort or filter by date on its side, so this runs here, before billing: older reviews are dropped and never charged. Set Max reviews per product to 0 with it, so recent reviews deep in the list are not missed.", "default": "" }, "requireText": { "title": "Only reviews with a written text", "type": "boolean", "description": "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.", "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", "enum": [ "default", "newest", "oldest", "lowest_rating", "highest_rating" ], "type": "string", "description": "The order the reviews are delivered in. AliExpress ignores every sort parameter its own endpoint accepts (verified 2026-08-29: complex_default, dateDescending and positive_first all return the identical page), so this actor orders the reviews it collected instead of pretending the site does. Newest/oldest use the review date; lowest rated first is the complaints feed.", "default": "default" }, "language": { "title": "Translation language", "enum": [ "en_US", "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" ], "type": "string", "description": "AliExpress machine-translates every review into one of sixteen languages of your choice — English, Spanish, Portuguese, French, German, Italian, Dutch, Polish, Turkish, Russian, Japanese, Korean, Arabic, Hebrew, Indonesian or Thai: text_translated comes back in this language whatever the buyer wrote in, and text keeps the original. It also decides the language the review date is written in, which the actor parses back to an ISO date for you. AliExpress translates lazily — a page nobody has opened before first answers with its translations missing — so the actor re-asks a cold page once and fills them in; you are never charged twice for that.", "default": "en_US" }, "includeProductRow": { "title": "Include a product row", "type": "boolean", "description": "Also emit one free row per product with its title, image, average rating, the full 1-5 star histogram, the positive/neutral/negative split, how many of its reviews carry photos or a follow-up, and the structured attributes buyers rated it on. It is what a product-research run actually wants, it costs one extra request per product, and it is never charged.", "default": true }, "hideBuyerDetails": { "title": "Hide buyer details", "type": "boolean", "description": "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 that is going into an LLM or a shared sentiment analysis pipeline.", "default": false }, "analyzeReviews": { "title": "Analyze reviews (sentiment, topics, insights)", "type": "boolean", "description": "Free AliExpress review analysis on top of the scrape. Every review row gains sentiment (positive / neutral / negative), a -1 to 1 sentiment_score, the topics it talks about — quality, delivery, packaging, size and fit, matches the description, value, durability, functionality, seller service, authenticity, damaged or missing — and rating_text_mismatch, which flags the 4 and 5 star reviews that read as complaints. Each product also gets one free insights row: the sentiment split, top complaints and top praise, and ratings broken down by SKU variant, buyer country and month. It is a transparent word list plus the star rating — no AI model, no outside service, no extra charge — and it reads English, so keep the translation language on English. Off by default; when off, the dataset is exactly what it always was.", "default": false }, "onlyNewReviews": { "title": "Only new reviews (monitoring mode)", "type": "boolean", "description": "Remember every review this actor has delivered to you and skip it next time. The first run is the baseline and delivers everything your filters keep; every later run delivers only reviews it has not given you before, and a review that was skipped is never charged. Put the actor on an Apify schedule with this on and you have an AliExpress review monitor: new complaints about a product you sell, or a competitor's, land in your dataset, webhook, Slack or Google Sheet the day they are written. Set Max reviews per product to 0 with it — AliExpress does not serve reviews newest-first, so a new review can sit anywhere in the list. Only delivered reviews are remembered, so one refused by your spending limit comes back on the next run.", "default": false }, "sessions": { "title": "Parallel sessions", "minimum": 1, "maximum": 16, "type": "integer", "description": "How many proxy sessions (egress IPs) run in parallel. More is faster; each is paced separately.", "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 } } } } } } } } } }