{ "openapi": "3.0.1", "info": { "title": "AliExpress Scraper - products, variants, prices & reviews", "description": "Scrape AliExpress products: search by keyword or category, or process pasted search, category and product URLs page by page. Identity, price, availability, media and SKU fields come from the results page; optional detail and reviews steps add variant tables, specifications, seller data and reviews.", "version": "1.0", "x-build-id": "RDvSEP096gg5rfkwB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~aliexpress-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-aliexpress-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/abotapi~aliexpress-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-aliexpress-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/abotapi~aliexpress-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-aliexpress-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", "required": [ "mode" ], "properties": { "mode": { "title": "Run mode", "enum": [ "search", "url" ], "type": "string", "description": "Pick how to start. 'search' runs the queries + filters below. 'url' walks one or more pasted search / category / product URLs forward, page by page. Product URLs emit a single product; search and category URLs walk their full result list.", "default": "search" }, "shippingCountry": { "title": "Target market", "enum": [ "us", "uk", "de", "fr", "es", "it", "br", "ca", "au", "nl", "pl" ], "type": "string", "description": "Which market to scrape. Pins the connection exit country and the currency/locale the storefront renders (prices come back in that market's currency). Defaults to the United States.", "default": "us" }, "queries": { "title": "Search keywords", "type": "array", "description": "One or more search terms. The actor runs a separate paginated walk for each keyword. Examples: 'airpods', 'led strip lights', 'phone case'. Only used when mode = search.", "items": { "type": "string" } }, "categoryId": { "title": "Category ID (optional)", "type": "string", "description": "Optional: restrict the keyword search to one AliExpress category id (the numeric id in a category URL such as /category/200003409/... or in the search refine panel). Leave empty for all categories." }, "freeShippingOnly": { "title": "Free shipping only", "type": "boolean", "description": "Request only items eligible for free shipping. Applied to the search request; on some results the storefront still mixes in non-eligible items.", "default": false }, "sortBy": { "title": "Sort order", "enum": [ "relevance", "bestSelling", "newest", "priceAsc", "priceDesc" ], "type": "string", "description": "Sort the search results. Best match is the storefront default.", "default": "relevance" }, "urls": { "title": "URLs", "type": "array", "description": "One or more AliExpress URLs. Search result pages (/w/wholesale-...html), category pages (/category/...html) and product pages (/item/.html) are all accepted. Multi-URL supported. Each search/category URL is walked forward from its starting page; filters are baked into the pasted URL, not reapplied here (the price/rating filters below still apply). Examples: https://www.aliexpress.com/w/wholesale-earbuds.html, https://www.aliexpress.com/category/200003409/electronics.html, https://www.aliexpress.com/item/1234567890123.html.", "items": { "type": "string" } }, "minPrice": { "title": "Min price", "minimum": 0, "type": "integer", "description": "Minimum price in the market's currency. Products below this are dropped. Applies to a keyword search and a pasted search or category URL. No bound when empty." }, "maxPrice": { "title": "Max price", "minimum": 0, "type": "integer", "description": "Maximum price in the market's currency. Products above this are dropped. Applies to a keyword search and a pasted search or category URL. No bound when empty." }, "minRating": { "title": "Minimum average rating", "minimum": 1, "maximum": 5, "type": "integer", "description": "Drop products whose average rating is below this value (1 to 5). Applied after the results are fetched. Applies to a keyword search and a pasted search or category URL, not just one mode." }, "reviewsOnly": { "title": "Output reviews only (instead of products)", "type": "boolean", "description": "When ON, the actor scans the results to discover product IDs but emits ONE record per review (type='review'), not one per product. Works in both modes.", "default": false }, "fetchReviews": { "title": "Include reviews on each product (slower, not recommended by default)", "type": "boolean", "description": "When ON and reviewsOnly is OFF, every product record additionally carries an embedded array of its top reviews (capped by Max reviews per product). This is a separate fetch per product - it adds real time and the same per-product detail-enrichment surcharge as Fetch full product detail below. We recommend leaving it OFF unless you specifically need review text; products with no reviews emit an empty list either way.", "default": false }, "maxReviewsPerProduct": { "title": "Max reviews per product", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Hard cap on reviews fetched per product.", "default": 100 }, "fetchDetails": { "title": "Fetch full product detail (slower, not recommended unless needed)", "type": "boolean", "description": "When ON, the actor visits each product's own detail page after the results, adding full SKU variant tables, specifications, description, seller data, and more. This is a separate fetch per product, so it meaningfully slows the run and adds a per-product detail-enrichment surcharge. We recommend leaving this OFF: the default (OFF) results-page fields already cover id, title, price, discount, rating, sold count, images and seller name, which is enough for most uses at much lower cost and speed. Turn ON only when you specifically need SKU variants, specs, or full seller data.", "default": false }, "maxPages": { "title": "Max result pages per query/URL", "minimum": 0, "type": "integer", "description": "Optional bound on result pages fetched per keyword or pasted search/category URL (the storefront serves ~60 cards per page). Leave empty (0) for no page limit - the run still stops at Max products total." }, "maxListings": { "title": "Max products total", "minimum": 0, "type": "integer", "description": "Hard cap across all keywords / URLs. Set to 0 for unlimited (still bounded by Max result pages). When reviewsOnly = true, this caps DISCOVERED products, not reviews; total review records can be much higher.", "default": 3 }, "resumeFromRunId": { "title": "Resume from a previous run", "type": "string", "description": "Paste a previous run ID or dataset ID to continue a full walk without returning or charging for products already collected there (matched by product id). Use this after an interrupted run, or to keep extending one pull across separate runs. For recurring daily/weekly monitoring of the same search, use Incremental mode below instead." }, "incrementalMode": { "title": "Incremental changes for scheduled runs", "type": "boolean", "description": "Turn this on for daily or recurring monitoring. The first run returns all matching products as NEW. Later runs normally return only NEW, UPDATED, and REAPPEARED products. Turn on \"Emit unchanged\" or \"Emit expired\" only when you also want those products returned (and billed). State is kept separately per mode + search/URL/filter configuration; use State key when you want to name or deliberately share a monitoring campaign. To continue one specific interrupted run instead, use Resume from a previous run above.", "default": false }, "stateKey": { "title": "State key (optional, incremental mode only)", "type": "string", "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently-configured runs. Leave empty to let the actor derive a key automatically from the mode + search/URL/filter settings - different searches then never mix state with each other." }, "emitUnchanged": { "title": "Emit unchanged products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that have not changed since the last run, marked UNCHANGED. This returns - and bills - extra rows you already have, so leave it off unless you specifically want the full snapshot every run.", "default": false }, "emitExpired": { "title": "Emit expired products (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return products that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search - not when Max products total capped it, when Resume was used, or in reviews-only mode. This returns - and bills - extra synthetic rows, so leave it off unless you need expiry tracking.", "default": false }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Apify Residential is required for the best results (the storefront refuses many shared exits; the actor warns at startup if the default group is not selected). The connection country is pinned to the Target market you selected. If the site keeps refusing connections mid-run, the actor rotates fresh exits - up to 12 browser launches per run, with any single result page attempted at most 5 times - and after half the launch budget is spent without a clean response it continues on Apify's unblocking proxy pool (group: UNBLOCKER), which is disclosed in the run log when used. A run refused on every connection fails loudly rather than returning an empty dataset." }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send the scraped results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize a connector once under Apify → Settings → Integrations, then select it here. The connector receives a condensed, human-readable summary per item (title + key fields), not the full JSON - the complete record stays in the dataset. Leave empty to skip. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL (or id) of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "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 } } } } } } } } } }