{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Scraper: Products, Prices & Reviews",
    "description": "Scrape AliExpress search results, product URLs and reviews: price, discount, units sold, rating, store, Choice, ship-from, delivery window, stock and landed price to your country. From $0.70 per 1,000 results, with every filter and sort, review star breakdowns and price and stock monitoring.",
    "version": "0.1",
    "x-build-id": "tI0uJ4Evjfxb2fUKU"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/cleanpull~aliexpress-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-cleanpull-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/cleanpull~aliexpress-scraper/runs": {
      "post": {
        "operationId": "runs-sync-cleanpull-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/cleanpull~aliexpress-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-cleanpull-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 terms",
            "type": "array",
            "description": "Products to search on AliExpress, one per line, as a shopper would type them (\"dog harness\", \"phone case\"). Each search is read page by page (60 results a page, two pages at once) up to Max results per search. Leave empty to use Start URLs or Product IDs only; with none of the three, the run uses the example.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs",
            "type": "array",
            "description": "Optional. AliExpress addresses: search pages (/w/wholesale-<words>.html, with any of their filters in the address) and product pages (/item/<id>.html, on aliexpress.com, .us, .ru or a language subdomain). Searches are read on www.aliexpress.us for your Ship to country. Category pages show no listings to automated readers, so they are skipped with a free row saying why; search their words instead.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "productIds": {
            "title": "Product IDs",
            "type": "array",
            "description": "Optional. AliExpress product ids, the digits in /item/<id>.html. Both forms work (1005… as on aliexpress.com, 3256… as on aliexpress.us search results); each row keeps the id as given and the other form in altId. Each product's page is read (price, stock, delivery, shipping cost, landed price).",
            "items": {
              "type": "string"
            }
          },
          "shipTo": {
            "title": "Ship to country",
            "pattern": "^[A-Za-z]{2}$",
            "type": "string",
            "description": "Two-letter country code of the shopper (US, GB, DE, FR, CA, AU…). AliExpress shows prices in that country's currency (GB: GBP), with its delivery dates and shipping cost, and searches list what ships there.",
            "default": "US"
          },
          "maxResultsPerSearch": {
            "title": "Max results per search",
            "minimum": 1,
            "maximum": 600,
            "type": "integer",
            "description": "Results delivered per search term or search address (default 60 = one page; up to 600 = 10 pages). A product listed by two searches is delivered once.",
            "default": 60
          },
          "maxResults": {
            "title": "Max results in all",
            "minimum": 1,
            "type": "integer",
            "description": "Optional. Stop once this many product rows are delivered across all searches, addresses and ids. Empty: no overall cap (Max results per search still applies). Reviews do not count."
          },
          "sort": {
            "title": "Sort",
            "enum": [
              "best-match",
              "orders",
              "price-asc",
              "price-desc"
            ],
            "type": "string",
            "description": "The order AliExpress sorts search results in. A search address keeps its own sort unless you choose one here.",
            "default": "best-match"
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "number",
            "description": "Optional. AliExpress's own price filter: results priced at or above this, in the Ship to country's currency."
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "number",
            "description": "Optional. AliExpress's own price filter: results priced at or below this, in the Ship to country's currency."
          },
          "freeShippingOnly": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "Only results AliExpress lists with free shipping to the Ship to country (its \"Free shipping\" filter).",
            "default": false
          },
          "choiceOnly": {
            "title": "Choice only",
            "type": "boolean",
            "description": "Only AliExpress Choice listings (AliExpress's \"Choice\" filter: faster, tracked delivery and free returns).",
            "default": false
          },
          "fourStarsAndUp": {
            "title": "4 stars and up",
            "type": "boolean",
            "description": "Only results rated 4 stars or more (AliExpress's \"& up\" quality filter).",
            "default": false
          },
          "shipFrom": {
            "title": "Ship from country",
            "pattern": "^([A-Za-z]{2})?$",
            "type": "string",
            "description": "Optional. Two-letter code of the warehouse country (US, CN, ES, FR…): AliExpress's \"Shipping from\" filter, for local-warehouse stock."
          },
          "includeDetails": {
            "title": "Include product details",
            "type": "boolean",
            "description": "Also read each search result's product page: in stock, units available, review count, option names and values, brand, store id and link, store rating and followers, shipping cost and method, landed price (price plus the shown shipping), purchase limit, price labels and the first specifications. Charged as Product details per row read. Products given by address or id always have these. Per-option prices and the full list of shipping methods are not on the page AliExpress serves, so they are not delivered.",
            "default": false
          },
          "includeReviews": {
            "title": "Include reviews",
            "type": "boolean",
            "description": "Also read buyer reviews of each delivered product (one row each: stars, text and its English translation, date, buyer country, option bought, shipping method, photos, helpful votes), with a free review-summary row per product holding the star breakdown and the buyers' tags.",
            "default": false
          },
          "maxReviewsPerProduct": {
            "title": "Max reviews per product",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Reviews delivered per product (20 a page). With Review stars set, up to five times as many pages are read to find matching reviews (at most 50 pages).",
            "default": 20
          },
          "reviewStars": {
            "title": "Review stars",
            "type": "array",
            "description": "Optional. Only reviews with these stars (for example 1 and 2 for complaints). AliExpress's review service has no star filter, so pages are read and the other reviews are left out (not charged).",
            "items": {
              "type": "string",
              "enum": [
                "1",
                "2",
                "3",
                "4",
                "5"
              ],
              "enumTitles": [
                "1 star",
                "2 stars",
                "3 stars",
                "4 stars",
                "5 stars"
              ]
            }
          },
          "includeReviewerNames": {
            "title": "Include reviewer names",
            "type": "boolean",
            "description": "Add the reviewer's name as AliExpress shows it (masked, \"U***r\"). Off by default: reviews are delivered without names, as personal data is not needed to read them.",
            "default": false
          },
          "onlyChanges": {
            "title": "Only changes (monitor)",
            "type": "boolean",
            "description": "Deliver only what changed since the last run of the same searches, products, Ship to country and Product details setting: new listings, price drops and rises, back in stock, out of stock, delivery and shipping changes, and products removed. Each row says changeType (added, updated, removed), changes and the previous values. Every run remembers what it delivered, so the first monitoring run after a plain run already compares. With reviews on, every watched product's reviews are checked (unchanged ones too) and only reviews not delivered before are delivered and charged: one review page read per product per run.",
            "default": false
          },
          "changeTypes": {
            "title": "Changes to report",
            "type": "array",
            "description": "Optional. Which changes Only changes reports. Empty: all but sold count changes (sold counts move almost every day).",
            "items": {
              "type": "string",
              "enum": [
                "new-listing",
                "price-drop",
                "price-rise",
                "back-in-stock",
                "out-of-stock",
                "delivery-change",
                "shipping-change",
                "sold-count-change",
                "removed"
              ],
              "enumTitles": [
                "New listing",
                "Price drop",
                "Price rise",
                "Back in stock",
                "Out of stock",
                "Delivery change (2+ days)",
                "Shipping change",
                "Sold count change",
                "Removed"
              ]
            }
          },
          "fields": {
            "title": "Output fields",
            "type": "array",
            "description": "Optional. Keep only these fields in product rows (dotted paths for nested ones: deliveryWindow.to); recordType, id, url, changeType, changes and previous always stay, and removed rows are delivered whole. Empty: every field. Review and summary rows are delivered whole.",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}