{ "openapi": "3.0.1", "info": { "title": "Aliexpress Scraper", "description": "Scrape AliExpress products by category, search, or URL into import-ready records — variants with per-SKU prices, stock and images, localized shipping, full image gallery, description and specifications. Choose your country, currency and language.", "version": "1.0", "x-build-id": "nYcoOoCresoqGlfis" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/ayen-data~aliexpress-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-ayen-data-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/ayen-data~aliexpress-scraper/runs": { "post": { "operationId": "runs-sync-ayen-data-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/ayen-data~aliexpress-scraper/run-sync": { "post": { "operationId": "run-sync-ayen-data-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", "properties": { "categoryIds": { "title": "Category IDs", "type": "array", "description": "AliExpress category IDs to scrape. The scraper opens each category, pages through the listings, and collects products up to your product limit. You can find a category ID in an AliExpress category page URL — e.g. in `aliexpress.com/category/1511/watches.html` the ID is `1511`. Add one or more.", "items": { "type": "string" } }, "startUrls": { "title": "Category or search URLs", "type": "array", "description": "Paste full AliExpress category or search-result page URLs instead of category IDs. Example: `https://www.aliexpress.com/category/1511/watches.html`. Every product found on those pages is scraped, up to your product limit.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "productUrls": { "title": "Product URLs", "type": "array", "description": "Scrape specific products only, by their product page URL (e.g. `https://www.aliexpress.com/item/1005006789883056.html`). When you use this, the scraper skips category browsing and goes straight to these products.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "productIds": { "title": "Product IDs", "type": "array", "description": "Scrape specific products only, by their numeric product ID (e.g. `1005006789883056`). Same as Product URLs, just shorter to paste.", "items": { "type": "string" } }, "maxItems": { "title": "Max products per source", "minimum": 1, "type": "integer", "description": "Maximum number of products to scrape from each category or search source. For example, with two category IDs and a limit of 100 you get up to 200 products. Does not apply when you scrape by product URL / ID.", "default": 100 }, "maxPagesPerCategory": { "title": "Max listing pages per source", "minimum": 1, "type": "integer", "description": "Optional cap on how many listing pages to open per category or search source. Leave empty to let the product limit above decide. AliExpress allows up to 100 pages per listing." }, "fetchDescription": { "title": "Include full product description", "type": "boolean", "description": "Include each product's full HTML description in the output. Turn off for faster, lighter runs when you only need titles, prices, variants and images.", "default": true }, "localeCountry": { "title": "Ship-to country", "enum": [ "US", "NL", "BE", "DE", "FR", "ES", "IT", "PT", "IE", "AT", "GB", "PL", "SE", "DK", "FI", "NO", "CH", "CZ", "CA", "AU", "BR", "RU", "SA", "AE", "IL" ], "type": "string", "description": "The country prices and shipping are calculated for. This decides the shipping cost, delivery time and destination in the output. For accurate results, use a proxy located in this same country (see Proxy below).", "default": "US" }, "localeCurrency": { "title": "Currency", "enum": [ "USD", "EUR", "GBP", "PLN", "SEK", "DKK", "NOK", "CHF", "CAD", "AUD", "BRL", "RUB", "AED", "SAR" ], "type": "string", "description": "The currency for all prices in the output.", "default": "USD" }, "localeLanguage": { "title": "Language", "enum": [ "en", "nl", "de", "fr", "es", "it", "pt", "pl", "sv", "ru", "ar" ], "type": "string", "description": "The language for product titles, option names and descriptions. Note: individual option values (like a colour name) come straight from the seller and may still appear in mixed languages.", "default": "en" }, "minSold": { "title": "Minimum times sold", "minimum": 0, "type": "integer", "description": "Keep only products that have been sold at least this many times. Leave empty for no limit." }, "minRating": { "title": "Minimum rating", "minimum": 0, "maximum": 5, "type": "integer", "description": "Keep only products rated at least this many stars (0–5). Leave empty for no limit." }, "minReviews": { "title": "Minimum number of reviews", "minimum": 0, "type": "integer", "description": "Keep only products with at least this many reviews. Leave empty for no limit." }, "allowedCategoryIds": { "title": "Only keep these category IDs (allowlist)", "type": "array", "description": "Optional allowlist. When set, a product is kept only if its own category — or any of its parent categories — is in this list. Useful when a broad category or search returns products from categories you don't want. Leave empty to keep products from every category.", "items": { "type": "string" } }, "blacklistSkuIds": { "title": "Skip these product variants (SKU IDs)", "type": "array", "description": "Optional list of AliExpress SKU IDs to skip — for example variants you have already imported. Any matching variant is removed from the output; if every variant of a product is on the list, the whole product is skipped.", "items": { "type": "string" } }, "blacklistUrl": { "title": "SKU list URL", "type": "string", "description": "Alternative to the list above for large sets: a link to a file of SKU IDs to skip. The file can be a JSON array, a JSON object like `{\"skus\": [...]}`, a CSV, or a plain text file with one ID per line. Merged with the inline list above." }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "A proxy is required to run reliably and to get correct localized prices and shipping. Use residential proxies and set the proxy country to the same country as your Ship-to country above — that is what makes shipping resolve to that country.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "localeLang": { "title": "Full locale override (advanced)", "type": "string", "description": "Advanced: set the full AliExpress locale as `language_COUNTRY` (e.g. `en_NL`). Leave empty to use the Language and Ship-to country selected above. Overrides the Language field when set." }, "minShopRating": { "title": "Minimum shop rating (%)", "minimum": 0, "maximum": 100, "type": "integer", "description": "Advanced: minimum seller positive-feedback percentage (0–100). Not always available; combine with the option below to control how missing values are treated." }, "excludeOnMissingFilterField": { "title": "Drop products when a filter value is missing", "type": "boolean", "description": "Advanced: when a filter is set but the value can't be read for a product, drop that product (on) or keep it and flag the missing value (off).", "default": false }, "sessionCookies": { "title": "Account cookies (for guaranteed shipping country)", "type": "array", "description": "Advanced and optional: AliExpress cookies exported from a browser logged in to an account in your Ship-to country. A good residential proxy is usually enough; provide these only if you need to guarantee the shipping country in edge cases." }, "maxConcurrency": { "title": "Max parallel workers", "minimum": 1, "maximum": 50, "type": "integer", "description": "Advanced: how many products to fetch in parallel. Higher is faster but more likely to hit rate limits. The default is a safe balance.", "default": 5 }, "maxReclaims": { "title": "Max retries on rate-limit", "minimum": 0, "type": "integer", "description": "Advanced: if a product is rate-limited, retry it up to this many times on a fresh proxy IP before giving up.", "default": 3 }, "discoveryConcurrency": { "title": "Max parallel listing pages", "minimum": 1, "maximum": 20, "type": "integer", "description": "Advanced: how many category/search listing pages to load in parallel while collecting products.", "default": 3 }, "maxRequestRetries": { "title": "Max listing page retries", "minimum": 0, "type": "integer", "description": "Advanced: how many times to retry a listing page that fails or is blocked before skipping it.", "default": 8 } } }, "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 } } } } } } } } } }