{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Scraper - Products, Prices, Orders & Supplier Leads",
    "description": "Scrape AliExpress products by keyword or URL: sale & original price, discount %, orders sold, rating, images, full SKU/variant matrix, live stock, shipping, specs, reviews & supplier leads. Choose currency & ship-to country, filter & monitor price drops.",
    "version": "0.1",
    "x-build-id": "9Kx5ipsZqJbY6xgqY"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/scrapesage~aliexpress-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-scrapesage-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/scrapesage~aliexpress-scraper/runs": {
      "post": {
        "operationId": "runs-sync-scrapesage-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/scrapesage~aliexpress-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-scrapesage-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": {
          "searchTerms": {
            "title": "Search keywords",
            "type": "array",
            "description": "Keywords to search AliExpress for, e.g. <code>wireless earbuds</code>, <code>phone case</code>, <code>led strip</code>. Each keyword is scraped as its own product feed, and several keywords share Max products equally. Leave empty if you only use Start URLs / Product IDs.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "AliExpress URLs to scrape directly: product pages (<code>/item/&lt;id&gt;.html</code>), search pages (<code>/w/wholesale-&lt;kw&gt;.html</code> or <code>/wholesale?SearchText=</code>, every filter in the link is kept), category pages (<code>/category/&lt;id&gt;/&lt;name&gt;.html</code>), store pages (<code>/store/&lt;id&gt;</code>) or short share links (<code>a.aliexpress.com/_...</code>). Used in addition to the keyword search. Links to other sites are skipped and named on the run card.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "urlsFromFile": {
            "title": "Import URLs from a file (one per line)",
            "type": "string",
            "description": "Bulk-load URLs without adding them one at a time. Either <b>paste your whole list</b> here, one URL per line, or give <b>a single link to the file</b> and it is downloaded for you - a public <code>.txt</code>/<code>.csv</code>, a Google Sheets or Drive share link (auto-converted to CSV export), or an Apify key-value-store record. Blank lines, <code>#</code> comments, quotes and extra CSV columns are ignored, and duplicates are only scraped once. A PDF, an Excel or Word file or an image is not read as a list: the run card says so (save it as .csv or .txt, or share it as a Google Sheet)."
          },
          "productIds": {
            "title": "Product IDs (direct detail)",
            "type": "array",
            "description": "AliExpress product IDs to fetch full product detail for directly (e.g. <code>1005006398294390</code>). Equivalent to pasting their item URLs. A product ID or product URL always returns the full record (its only source is AliExpress's product data), billed at the detailed product price; an ID AliExpress does not have is named on the run card and not billed.",
            "items": {
              "type": "string"
            }
          },
          "sort": {
            "title": "Sort order",
            "enum": [
              "default",
              "orders",
              "newest",
              "priceAsc",
              "priceDesc"
            ],
            "type": "string",
            "description": "How AliExpress orders the search results. AliExpress's search no longer offers a newest-first order: a Newest run gets its best-match order (use Monitor mode to get only products new since your last run). The run card says so whenever AliExpress applied a different order.",
            "default": "default"
          },
          "minPrice": {
            "title": "Min price",
            "minimum": 0,
            "type": "number",
            "description": "Only keep products whose sale price (in the chosen currency) is at least this much. Sent to AliExpress as its own price filter on keyword searches and pasted search links, and checked again on every delivered row."
          },
          "maxPrice": {
            "title": "Max price",
            "minimum": 0,
            "type": "number",
            "description": "Only keep products whose sale price (in the chosen currency) is at most this much. Sent to AliExpress as its own price filter on keyword searches and pasted search links, and checked again on every delivered row."
          },
          "fourStarPlus": {
            "title": "4 stars & up only",
            "type": "boolean",
            "description": "Only keep products with an average rating of 4.0 stars or higher (drops new/unrated and low-rated items). Sent to AliExpress as its \"4 stars & up\" filter on keyword searches and pasted search links, and checked again on every delivered row.",
            "default": false
          },
          "choiceOnly": {
            "title": "AliExpress Choice only",
            "type": "boolean",
            "description": "Only keep AliExpress Choice products (faster shipping / curated). Sent to AliExpress as its Choice filter on keyword searches and pasted search links, and checked again on every delivered row.",
            "default": false
          },
          "freeShippingOnly": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "Only keep products AliExpress lists with free shipping. Sent to AliExpress as its Free shipping filter on keyword searches and pasted search links, and checked again on every delivered row; with product details on, the row's own shipping fee must also read Free.",
            "default": false
          },
          "shipToCountry": {
            "title": "Ship-to country",
            "type": "string",
            "description": "Country that prices and availability are localized to: a two-letter code (<code>US</code>, <code>GB</code>, <code>DE</code>, <code>AU</code>, <code>BR</code>) or the English name (<code>Germany</code>, <code>United Kingdom</code>). AliExpress's product-detail data is made for US delivery only, so with another country the detail rows keep the search page's own prices for that country and leave the shipping block empty.",
            "default": "US"
          },
          "currency": {
            "title": "Currency",
            "type": "string",
            "description": "Currency code for all prices (e.g. <code>USD</code>, <code>EUR</code>, <code>GBP</code>). AliExpress converts to this currency.",
            "default": "USD"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Locale for titles, specs and reviews (e.g. <code>en_US</code>, <code>es_ES</code>, <code>fr_FR</code>, <code>de_DE</code>, <code>pt_BR</code>).",
            "default": "en_US"
          },
          "maxProducts": {
            "title": "Max products",
            "minimum": 1,
            "type": "integer",
            "description": "Maximum number of product records to scrape across all searches/URLs. Product IDs and product URLs come first; keyword searches, categories and stores then share the rest equally (one with fewer products leaves its share to the next). AliExpress search returns ~60 products per page.",
            "default": 100
          },
          "includeProductDetails": {
            "title": "Include full product detail",
            "type": "boolean",
            "description": "Open each product to add the full SKU/variant matrix (per-option price & stock), live total inventory, review count, all images & video, shipping options (fee/ETA/carrier), full specifications, description URL, coupons and the supplier/store profile. Adds one API call per product. Product URLs and IDs always return the full record.",
            "default": false
          },
          "includeReviews": {
            "title": "Include buyer reviews",
            "type": "boolean",
            "description": "Fetch buyer reviews per product (rating, text, country, photos, purchased SKU) plus the star-rating breakdown on the product row (reviewStats). Each review is delivered once per run, even when linked listings share it. Adds one or more API calls per product.",
            "default": false
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": 1,
            "maximum": 200,
            "type": "integer",
            "description": "Maximum number of buyer reviews to pull per product when reviews are enabled (20 per page).",
            "default": 20
          },
          "reviewSort": {
            "title": "Review sort",
            "enum": [
              "default",
              "newest",
              "photo",
              "positive",
              "negative"
            ],
            "type": "string",
            "description": "Which buyer reviews come first. With photos uses AliExpress's own photo filter (only reviews with photos). AliExpress's review feed has no newest, positive or critical order, so for those the Actor reads up to 4 pages more than Max reviews per product needs and orders those reviews itself.",
            "default": "default"
          },
          "emitStoreLeads": {
            "title": "Emit supplier/store lead records",
            "type": "boolean",
            "description": "In addition to product records, push one deduplicated lead record per unique store (type = \"store\") with the store URL, seller level, years open, country, top-rated badge, product count and a 0-100 lead score. (Implies product detail. Note: AliExpress does not publish seller emails/phones - contact is via the platform.)",
            "default": false
          },
          "deduplicateProducts": {
            "title": "Deduplicate products",
            "type": "boolean",
            "description": "Drop duplicate products that appear in more than one search/page in the same run (matched on both the card's id and AliExpress's item id).",
            "default": true
          },
          "monitorMode": {
            "title": "Monitor mode (only new / changed)",
            "type": "boolean",
            "description": "Remember products across runs in a named key-value store and emit ONLY products that are new OR whose price/stock changed since last run (each carries a <code>changeType</code>: new / price_drop / price_rise / restocked / out_of_stock). Each run watches the first Max products of each search; an unchanged product is not billed. Pair with Apify Schedules for price-drop & restock alerts - it complements the scheduler (the schedule starts the run, monitor mode dedupes against prior runs).",
            "default": false
          },
          "monitorKey": {
            "title": "Monitor key",
            "type": "string",
            "description": "Names the monitor's memory store so you can run several independent monitors (e.g. one per keyword). Reuse the same key to keep tracking the same feed.",
            "default": "default"
          },
          "maxConcurrency": {
            "title": "Max concurrency",
            "minimum": 1,
            "maximum": 8,
            "type": "integer",
            "description": "Parallel page/API fetches. Keep low (2 to 4) so AliExpress's anti-bot doesn't challenge the proxy.",
            "default": 3
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxies to use. With the default (Apify Proxy, residential) the Actor asks AliExpress through Apify datacenter proxies first and switches to residential proxies when AliExpress refuses them. Any other choice (a country, other proxy groups, your own proxy URLs, no proxy) is used exactly as given.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ]
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}