{ "openapi": "3.0.1", "info": { "title": "AliExpress Reviews Scraper — Product Feedback & Ratings", "description": "Every AliExpress buyer review of any product: star rating, the buyer's own words plus a translation, buyer country, the SKU variant bought, their photos, the shipping method and the follow-up review. Product URLs or item ids in, reviews out. No key, no login, no browser. Pay per review.", "version": "1.0", "x-build-id": "NFs7dV5qfOyUS0RHG" }, "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.", "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" } }, "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 }, "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 }, "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" ], "type": "string", "description": "AliExpress machine-translates every review into one language of your choice: 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.", "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 }, "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 } } }, "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 } } } } } } } } } }