{
"openapi": "3.0.1",
"info": {
"title": "AliExpress Scraper: Products, Reviews & Stores",
"description": "Scrape AliExpress products, prices, variants, stock, reviews, sellers, shipping, supplier stores, and monitor product changes with localized data.",
"version": "1.4",
"x-build-id": "qPci2R87Y0MnIp4Um"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/studio_sussex~aliexpress-product-scraper/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-studio_sussex-aliexpress-product-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/studio_sussex~aliexpress-product-scraper/runs": {
"post": {
"operationId": "runs-sync-studio_sussex-aliexpress-product-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/studio_sussex~aliexpress-product-scraper/run-sync": {
"post": {
"operationId": "run-sync-studio_sussex-aliexpress-product-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": {
"mode": {
"title": "Workflow",
"enum": [
"auto",
"search",
"details",
"reviews",
"monitor",
"store"
],
"type": "string",
"description": "Recommended: Auto-detect. Keywords run search, exact product links default to full details, and store links run supplier discovery. Choose a specific workflow when you want reviews or monitoring.",
"default": "auto"
},
"searchQueries": {
"title": "Search keywords",
"minItems": 0,
"maxItems": 25,
"type": "array",
"description": "Keywords to search on AliExpress. Leave empty when using URLs, product IDs, or store IDs.",
"default": [],
"items": {
"type": "string"
}
},
"startUrls": {
"title": "Search or category URLs",
"maxItems": 25,
"type": "array",
"description": "AliExpress keyword-search or category result URLs. Product detail URLs belong in Product URLs/IDs; store URLs belong in Store URLs/IDs.",
"items": {
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"title": "URL of a web page",
"format": "uri"
}
}
}
},
"productUrls": {
"title": "Product URLs / IDs / share links",
"maxItems": 1000,
"type": "array",
"description": "Exact AliExpress product URLs, numeric IDs, regional URLs, or official AliExpress short/share links. Up to 1,000 direct products per run; short links are resolved automatically.",
"default": [],
"items": {
"type": "string"
}
},
"storeUrls": {
"title": "Store / supplier URLs or IDs",
"maxItems": 20,
"type": "array",
"description": "AliExpress store URLs or numeric store IDs. Store mode renders the all-items page, calls its signed catalog API with bounded paging, and collects unique products plus supplier metadata.",
"default": [],
"items": {
"type": "string"
}
},
"maxResults": {
"title": "Maximum results",
"minimum": 1,
"maximum": 25000,
"type": "integer",
"description": "Hard product-output cap. Keeps run size and spend predictable. Reviews have separate caps below.",
"default": 20
},
"sortBy": {
"title": "Sort order",
"enum": [
"relevance",
"orders",
"price_asc",
"price_desc"
],
"type": "string",
"description": "Only sort modes verified against live AliExpress listings are offered. 'relevance' is the site default.",
"default": "relevance"
},
"minPrice": {
"title": "Minimum price",
"minimum": 0,
"type": "number",
"description": "Minimum product price in the currency AliExpress actually serves for the selected market."
},
"maxPrice": {
"title": "Maximum price",
"minimum": 0,
"type": "number",
"description": "Maximum product price in the currency AliExpress actually serves for the selected market."
},
"minRating": {
"title": "Minimum rating",
"minimum": 0,
"maximum": 5,
"type": "number",
"description": "Keep products rated at least this high (0-5). Products without a rating are dropped when set."
},
"minSold": {
"title": "Minimum sold count",
"minimum": 0,
"type": "integer",
"description": "Keep products with at least this many reported orders. Uses the exact order count when AliExpress exposes it."
},
"minDiscountPercent": {
"title": "Minimum discount %",
"minimum": 0,
"maximum": 99,
"type": "number",
"description": "Keep only products with at least this displayed/derived discount percentage."
},
"choiceOnly": {
"title": "Choice products only",
"type": "boolean",
"description": "Keep only products AliExpress marks as Choice.",
"default": false
},
"freeShippingOnly": {
"title": "Free shipping only",
"type": "boolean",
"description": "Keep only products whose search card explicitly carries the Free Shipping badge.",
"default": false
},
"shipFromCountry": {
"title": "Ship-from country code",
"pattern": "^[a-zA-Z]{2}$",
"type": "string",
"description": "Two-letter country code reported per product, e.g. US or CN."
},
"includeSponsored": {
"title": "Include sponsored products",
"type": "boolean",
"description": "AliExpress marks ads in the search results (isSponsored = true). Turn off for organic listings only.",
"default": true
},
"deduplicateAcrossQueries": {
"title": "Deduplicate across queries",
"type": "boolean",
"description": "By default each query keeps its own rows (a product matching two queries is emitted twice with different searchQuery values). Turn on to emit each product once per run.",
"default": false
},
"rotateSorts": {
"title": "Rotate sort modes when results repeat",
"type": "boolean",
"description": "AliExpress repeats listings across pages. When a sort stops producing new products, continue with the other verified sort modes to reach maxResults. Each row records the sort it came from.",
"default": true
},
"targetCountry": {
"title": "Target country",
"pattern": "^[a-zA-Z]{2}$",
"type": "string",
"description": "Two-letter ship-to/proxy country such as US, GB, DE, FR, AU. The Actor automatically uses a residential IP in this country on Apify cloud.",
"default": "US"
},
"targetCurrency": {
"title": "Target currency",
"pattern": "^[a-zA-Z]{3}$",
"type": "string",
"description": "Requested three-letter display currency such as USD, EUR, GBP, AUD. Returned rows always report the currency AliExpress actually served.",
"default": "USD"
},
"locale": {
"title": "Language / locale",
"pattern": "^[a-zA-Z]{2}([_-][a-zA-Z]{2})?$",
"type": "string",
"description": "Requested AliExpress locale such as en_US, de_DE, fr_FR, es_ES.",
"default": "en_US"
},
"includeDetails": {
"title": "Full product details",
"type": "boolean",
"description": "Open each product through a real browser and collect variants, SKU pricing, stock, seller, specifications, shipping and full gallery data. Automatically enabled for direct product URLs/IDs.",
"default": false
},
"includeDescription": {
"title": "Include product description",
"type": "boolean",
"description": "Fetch description HTML/text after successful full-detail capture.",
"default": false
},
"includeReviews": {
"title": "Collect buyer reviews",
"type": "boolean",
"description": "Collect separate buyer-review rows and attach review statistics + derived review intelligence to the product.",
"default": false
},
"detailConcurrency": {
"title": "Detail concurrency",
"minimum": 1,
"maximum": 6,
"type": "integer",
"description": "Maximum simultaneous browser product-detail contexts. Default 2 is reliability-first; raise only after your cloud workload is stable.",
"default": 2
},
"minReviewRating": {
"title": "Minimum review rating",
"minimum": 1,
"maximum": 5,
"type": "number",
"description": "Optional review filter: keep reviews rated at least this many stars."
},
"maxReviewRating": {
"title": "Maximum review rating",
"minimum": 1,
"maximum": 5,
"type": "number",
"description": "Optional review filter: useful for finding negative/low-star reviews."
},
"reviewsWithMediaOnly": {
"title": "Reviews with photos/video only",
"type": "boolean",
"description": "Return only reviews containing at least one image or video.",
"default": false
},
"reviewCountry": {
"title": "Reviewer country",
"pattern": "^[a-zA-Z]{2}$",
"type": "string",
"description": "Optional two-letter reviewer-country filter, e.g. US, DE, GB."
},
"reviewKeyword": {
"title": "Review keyword",
"type": "string",
"description": "Optional case-insensitive keyword filter across original, translated, and follow-up review text."
},
"reviewsSinceDate": {
"title": "Reviews since date",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string",
"description": "Optional YYYY-MM-DD cutoff. Reviews with missing/unparseable dates are excluded when this is set."
},
"hideReviewerName": {
"title": "Hide buyer display names",
"type": "boolean",
"description": "Remove reviewerName from emitted review rows while keeping country and non-identifying research fields.",
"default": false
},
"onlyNewReviews": {
"title": "Only new reviews since prior run",
"type": "boolean",
"description": "Persist review identities per product/market/locale and emit/bill only reviews not seen in earlier runs. Applies within the review window actually fetched; it does not claim complete review-history coverage.",
"default": false
},
"maxReviewsPerProduct": {
"title": "Maximum reviews per product",
"minimum": 1,
"maximum": 5000,
"type": "integer",
"description": "Maximum matching review rows per product (up to 5,000). Availability at deep pages depends on what AliExpress exposes.",
"default": 20
},
"maxTotalReviews": {
"title": "Maximum reviews for the whole run",
"minimum": 1,
"maximum": 50000,
"type": "integer",
"description": "Whole-run review-row cap. This is the main review spending guard.",
"default": 1000
},
"maxReviewScanPages": {
"title": "Maximum review pages to scan",
"minimum": 1,
"maximum": 250,
"type": "integer",
"description": "Safety cap for pages scanned while finding matching reviews. Raise only when using restrictive review filters.",
"default": 20
},
"monitorChanges": {
"title": "Monitor changes",
"type": "boolean",
"description": "Persist product state in your own Apify account and emit only first-seen or changed products by default. Useful for scheduled price, sales, rating and stock monitoring.",
"default": false
},
"emitUnchanged": {
"title": "Also emit unchanged products",
"type": "boolean",
"description": "When monitoring, also return unchanged products. Leave off for change-only output and lower billing.",
"default": false
},
"resumeDataset": {
"title": "Resume from dataset (optional)",
"type": "string",
"description": "Select a previous Apify dataset to continue without re-emitting products already completed there. Search/store skips prior products; details skips products with completed full detail. API callers can also pass the dataset ID/name directly."
},
"storeSort": {
"title": "Store product sort",
"enum": [
"default",
"bestmatch",
"orders",
"new",
"price"
],
"type": "string",
"description": "Requested ordering for products on the AliExpress store all-items page.",
"default": "default"
},
"maxStoreScrolls": {
"title": "Maximum store scroll rounds",
"minimum": 0,
"maximum": 60,
"type": "integer",
"description": "Safety cap for signed store-catalog page rounds and rendered-page fallback scrolling. Stops early when no new product IDs are exposed.",
"default": 20
},
"maxPagesPerQuery": {
"title": "Maximum pages per query",
"minimum": 1,
"maximum": 40,
"type": "integer",
"description": "Safety ceiling on listing pages fetched per query (and per sort mode).",
"default": 20
},
"maxRequests": {
"title": "Maximum HTTP requests",
"minimum": 1,
"maximum": 2000,
"type": "integer",
"description": "Hard request budget for the whole run, retries included.",
"default": 100
},
"minDelayMs": {
"title": "Minimum delay between requests (ms)",
"minimum": 0,
"maximum": 60000,
"type": "integer",
"description": "Global pacing floor between page fetches. Cloud runs rotate residential IPs automatically; increase this only if AliExpress still reports blocks.",
"default": 750
},
"requestTimeoutMs": {
"title": "Request timeout",
"minimum": 5000,
"maximum": 120000,
"type": "integer",
"description": "Timeout for a single HTTP request.",
"default": 30000
},
"maxRetries": {
"title": "Maximum retries",
"minimum": 0,
"maximum": 6,
"type": "integer",
"description": "Retry ceiling for retryable transport/server errors.",
"default": 3
},
"keepRawCard": {
"title": "Keep raw source card",
"type": "boolean",
"description": "Attach the unmodified AliExpress card JSON to each row under rawCard. Makes rows much larger; use for debugging only.",
"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
}
}
}
}
}
}
}
}
}
}