{ "openapi": "3.0.1", "info": { "title": "AliExpress Products Scraper", "description": "Scrape AliExpress products by keyword, category or URL, in 51 countries: price, discount, units sold, rating, delivery, seller and reviews. Export to JSON, CSV or Excel.", "version": "0.0", "x-build-id": "7It3r7pzvmoCirqo1" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~aliexpress-products-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-aliexpress-products-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/nice_dev~aliexpress-products-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-aliexpress-products-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/nice_dev~aliexpress-products-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-aliexpress-products-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": "Start URLs", "maxItems": 1000, "type": "array", "description": "AliExpress search URLs (`https://www.aliexpress.com/w/wholesale-phone-case.html`, every filter set on the site is kept), category URLs (`https://www.aliexpress.com/category/100003109/women-clothing.html`) or product URLs (`https://www.aliexpress.com/item/1005006123456789.html`). Pagination is automatic. When this list is not empty, the keyword and category fields below are ignored; filters, caps and monitoring still apply. Max 1 000 URLs × delivery countries (500 URLs in 2 countries).", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "query": { "title": "Search keyword", "maxLength": 200, "type": "string", "description": "Free-text search, exactly as typed on AliExpress (e.g. `wireless earbuds`)." }, "searchQueries": { "title": "More search keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword (times each country below). Added to **Search keyword**; products found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "categoryId": { "title": "Category ID", "pattern": "^[0-9]{1,15}$", "maxLength": 15, "type": "string", "description": "AliExpress category number, read in a category URL (`/category/100003109/...` → `100003109`) or in the `categoryId` field of a previous run. With a keyword: the keyword searched inside this category. Alone: the whole category." }, "productUrls": { "title": "Product URLs or IDs", "maxItems": 1000, "uniqueItems": true, "type": "array", "description": "Single products to read, as URLs (`https://www.aliexpress.com/item/1005006123456789.html`, any AliExpress country domain or app share link) or bare product IDs (`1005006123456789`). Each one is read from its product page, so it is charged as a product with full details. Max 1 000.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max products", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of products to save for the whole run (after deduplication and filters). 0 = no limit.", "default": 100 }, "maxItemsPerQuery": { "title": "Max products per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap for EACH search (keyword × country, category, or search URL), so that the first search cannot use up the whole **Max products** budget. 0 = no per-search cap.", "default": 0 }, "splitByPrice": { "title": "Go past AliExpress's 3,600-product limit", "type": "boolean", "description": "AliExpress shows at most 60 pages (≈ 3,600 products) per search. When a search fills them, the Actor splits it into price ranges and reads each range, so a large search returns far more products. Off = stop at 3,600 per search. Not used when sorted by price: that search stops at about 3,600 products, in the order of the sort.", "default": true }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "orders", "price_asc", "price_desc" ], "type": "string", "description": "Order of the search results, as on AliExpress. AliExpress has no 'newest' order: use **Only new products** below to get the new ones at each run.", "default": "relevance" }, "minPrice": { "title": "Min price", "minimum": 0, "maximum": 1000000000, "type": "number", "description": "Only products from this price, in the currency below. Sent to AliExpress." }, "maxPrice": { "title": "Max price", "minimum": 0, "maximum": 1000000000, "type": "number", "description": "Only products up to this price, in the currency below. Sent to AliExpress. 0 = no maximum." }, "freeShippingOnly": { "title": "Free shipping only", "type": "boolean", "description": "AliExpress filter 'Free shipping'.", "default": false }, "choiceOnly": { "title": "Choice products only", "type": "boolean", "description": "AliExpress filter 'Choice' (AliExpress's own selection: free shipping, faster delivery, free returns).", "default": false }, "saleOnly": { "title": "On sale only", "type": "boolean", "description": "AliExpress filter 'Sale' (products in the current promotion).", "default": false }, "localWarehouseOnly": { "title": "Local warehouse only", "type": "boolean", "description": "AliExpress filter 'Local+': products shipped from a warehouse in the delivery country (faster delivery). Applied to searches.", "default": false }, "shipFromCountry": { "title": "Ships from (country code)", "pattern": "^[A-Za-z]{2}$", "maxLength": 2, "type": "string", "description": "Only products shipped from this country, as a 2-letter code: `CN`, `US`, `ES`, `FR`, `DE`, `PL`… Empty = any origin. Sent to AliExpress for searches." }, "country": { "title": "Ship to (country)", "enum": [ "US", "GB", "CA", "AU", "NZ", "IE", "DE", "FR", "ES", "IT", "NL", "BE", "PL", "PT", "SE", "CH", "AT", "DK", "FI", "NO", "CZ", "RO", "HU", "GR", "SK", "BG", "UA", "TR", "IL", "SA", "AE", "JP", "KR", "SG", "MY", "TH", "PH", "VN", "ID", "IN", "PK", "MX", "BR", "CL", "CO", "PE", "AR", "ZA", "NG", "EG", "MA" ], "type": "string", "description": "Country the products are delivered to: AliExpress shows the prices, shipping options and products of this country.", "default": "US" }, "countries": { "title": "More countries", "maxItems": 51, "uniqueItems": true, "type": "array", "description": "Several delivery countries in one run, as 2-letter codes (`GB`, `DE`, `FR`…): every keyword is searched in every country (3 keywords × 4 countries = 12 searches, max 500), to compare prices between countries. Added to **Ship to**. A product found in two countries is saved once per country.", "default": [], "items": { "type": "string" } }, "currency": { "title": "Currency", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "NZD", "CHF", "SEK", "NOK", "DKK", "PLN", "CZK", "HUF", "RON", "BGN", "UAH", "TRY", "ILS", "SAR", "AED", "KZT", "JPY", "KRW", "SGD", "MYR", "THB", "PHP", "VND", "IDR", "INR", "PKR", "MXN", "BRL", "CLP", "COP", "PEN", "ZAR", "NGN", "EGP", "MAD" ], "type": "string", "description": "Currency of the prices.", "default": "USD" }, "language": { "title": "Language", "enum": [ "en_US", "fr_FR", "de_DE", "es_ES", "it_IT", "pt_BR", "nl_NL", "pl_PL", "ru_RU", "tr_TR", "ja_JP", "ko_KR", "ar_MA", "iw_IL", "th_TH", "in_ID" ], "type": "string", "description": "Language of the titles and specifications (AliExpress's own translation). Reviews always come with an English translation, whatever this field.", "default": "en_US" }, "extractDetails": { "title": "Full product details", "type": "boolean", "description": "Read each product's page: every variant (color, size…) with its price and stock, total stock, shipping options to the delivery country (cost, carrier, delivery days), specifications, category path, number of reviews, seller (store name, number, country, opening date, positive feedback, top-rated) and all photos. Charged per product read (event `product-details`).", "default": false }, "includeDescription": { "title": "Include the description", "type": "boolean", "description": "With **Full product details**: also the seller's description (text and image URLs). No extra charge.", "default": true }, "includeReviews": { "title": "Include buyer reviews", "type": "boolean", "description": "Add each product's buyer reviews (rating, text and its translation, date, buyer country, variant bought, photos, helpful votes, follow-up review) and its rating breakdown (count per star). Charged per review (event `review`).", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Reviews kept per product, in AliExpress's default order. Read 50 at a time.", "default": 20 }, "reviewFilter": { "title": "Reviews to keep", "enum": [ "all", "image", "additional", "local" ], "type": "string", "description": "AliExpress's review filter: every review, only those with photos, only those with a follow-up review, or only those from buyers in the delivery country.", "default": "all" }, "reviewMinRating": { "title": "Reviews: min stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only the reviews with at least this many stars (1-5). Empty = all." }, "reviewMaxRating": { "title": "Reviews: max stars", "minimum": 1, "maximum": 5, "type": "integer", "description": "Keep only the reviews with at most this many stars, e.g. 2 for the complaints. Empty = all." }, "reviewKeyword": { "title": "Reviews: word to find", "maxLength": 100, "type": "string", "description": "Keep only the reviews whose text, or its English translation, contains this word or phrase (case and accents ignored), e.g. `battery` or `broke`. AliExpress cannot filter reviews by text, so the Actor reads more pages to find enough of them. Empty = all." }, "reviewPostedAfter": { "title": "Reviews: posted after", "type": "string", "description": "Keep only the reviews written on or after this date: `2026-03-01`, or a period before now such as `30 days`, `3 months`. Reviews without a readable date are dropped. Empty = all." }, "postedAfter": { "title": "Listed after", "type": "string", "description": "Only products first listed on AliExpress on or after this date (the launch date AliExpress shows in the search results): `2026-09-01`, or a period before now such as `7 days`, `2 weeks`, `1 month`. Products without a launch date are dropped." }, "postedBefore": { "title": "Listed before", "type": "string", "description": "Only products first listed on or before this date (the whole day is included), or older than a period such as `30 days`." }, "minRating": { "title": "Min rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Only products rated at least this (out of 5). 4 or more also uses AliExpress's own '4 stars & up' filter. Products without a rating are dropped." }, "minOrders": { "title": "Min units sold", "minimum": 0, "maximum": 1000000000, "type": "integer", "description": "Only products with at least this many units sold, as AliExpress shows it ('1,000+ sold' counts as 1000)." }, "minDiscountPercent": { "title": "Min discount (%)", "minimum": 0, "maximum": 100, "type": "integer", "description": "Only products whose search card shows at least this discount (the crossed-out price against the sale price), e.g. `50`. Products that show no discount are dropped. Empty or 0 = no bound." }, "expiringWithinHours": { "title": "Promotion ends within (hours)", "minimum": 1, "maximum": 8760, "type": "integer", "description": "Only products whose promotion ends from now on and within this many hours. The end date is on the product page: needs **Full product details** (without it this filter is ignored). A dropped product is charged a detail filter fee (see Pricing)." }, "onlyWithExpiry": { "title": "Only products with a promotion end date", "type": "boolean", "description": "Only products whose product page gives the end date of their promotion. Needs **Full product details** (without it this filter is ignored). A dropped product is charged a detail filter fee (see Pricing).", "default": false }, "excludeSponsored": { "title": "Exclude sponsored products", "type": "boolean", "description": "Drop the products AliExpress marks as ads in the search results.", "default": false }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the products whose title contains one of these words (case and accents ignored).", "default": [], "items": { "type": "string" } }, "onlyNew": { "title": "Only new products", "type": "boolean", "description": "Skip the products that a previous run (same **Memory key**) already delivered: they are not saved and not charged, and their page is not even opened. First run = everything is new. A search stops after 20 results pages in a row with nothing new.", "default": false }, "includePriceChanges": { "title": "Also products whose price changed (paid option)", "type": "boolean", "description": "With **Only new products**: also return the products already delivered whose price went up or down since the last run, with the previous price, the change in % and the price history of your runs. Charged per changed product (event `price-change`).", "default": false }, "minPriceChangePercent": { "title": "Minimum price change (%)", "minimum": 0, "maximum": 90, "type": "number", "description": "With **Also products whose price changed**: a product comes back only if its price moved by at least this many % since the last time it was delivered. The price followed is the seller's price (`sellerOfferPrice`): the price AliExpress displays varies with every visit, so it is never compared. Under this %, the move (a currency conversion, a rounding) is neither returned nor charged. 0 = every change down to the cent.", "default": 3 }, "includeRemoved": { "title": "Also products that left the results", "type": "boolean", "description": "With **Also products whose price changed**: also return a row (`changeType` = `removed`) for each product an earlier run delivered that its search no longer lists. Only for a keyword or category search that the run read to its very end (fewer than 3,600 products, no failed request, run not resumed). Each row is charged as a product.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new products**. Give each schedule / task its own key (e.g. `earbuds-us`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every product again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price, and the Actor switches IP by itself when AliExpress slows one down. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 5 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 10, "maximum": 2000, "type": "integer", "description": "Most requests to AliExpress in any 60 seconds, all of them counted: search pages, product pages, review pages. A budget, not an even pace: up to this many can leave at once when the minute starts (spread them with the minimum delay below). Lower it if the log shows many 'Blocked' or 'Rate-limited' lines.", "default": 120 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Smallest gap between two requests, in milliseconds. Unlike the per-minute rate, this spreads the requests evenly instead of letting them go out in a burst. 0 = no gap.", "default": 0 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed. Behind a proxy, a request AliExpress turns away is also retried on a new proxy session up to 10 times without using up these retries.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "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 }, "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 } } } } } } } } } }