{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Product Search Scraper",
    "description": "Search AliExpress by keyword (several at once) or search URL: title, price, discount, rating, orders, Choice badge, free shipping, delivery estimate, store, image, URL. Filter by sort, price, ship-from, Choice, rating, orders; set currency and language. Fast, MCP-ready.",
    "version": "1.0",
    "x-build-id": "VUyJ7VcAMZNT66mxu"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~aliexpress-product-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-aliexpress-product-search-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/khadinakbar~aliexpress-product-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-aliexpress-product-search-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/khadinakbar~aliexpress-product-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-aliexpress-product-search-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": {
          "searchQuery": {
            "title": "Search keyword",
            "type": "string",
            "description": "Free-text keyword to search AliExpress products (e.g. 'wireless earbuds'). The Actor reads the search results page by page and returns one record per product card. Add more keywords in 'More keywords', or leave this empty and use start URLs. This is a search, not a single product page."
          },
          "searchQueries": {
            "title": "More keywords",
            "type": "array",
            "description": "Extra keywords, one search each (for example 'phone case', 'usb hub'). Combined with 'Search keyword'. A product found by several keywords is returned once, under the first keyword that found it. The 'Max products' limit covers all keywords together.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Start URLs (search/category pages)",
            "type": "array",
            "description": "Optional list of AliExpress search or category URLs to scrape directly (e.g. https://www.aliexpress.com/w/wholesale-led-strip.html or a /category/ URL). Use this instead of, or together with, searchQuery. Product URLs (/item/...) and non-AliExpress URLs are ignored — this Actor only scrapes search/category result pages.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "maxResults": {
            "title": "Max products",
            "minimum": 1,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of product records to return. The Actor auto-paginates until this cap is reached, then stops, so it doubles as your cost ceiling (each product is one billable event). Defaults to 100. Set higher for bulk research. Free Apify plan runs return up to 25 products per run.",
            "default": 100
          },
          "sortBy": {
            "title": "Sort results by",
            "enum": [
              "relevance",
              "ordersDesc",
              "priceAsc",
              "priceDesc",
              "newest"
            ],
            "type": "string",
            "description": "Order in which AliExpress returns the search results. 'relevance' is AliExpress Best Match (default); 'ordersDesc' is best-selling first; 'priceAsc'/'priceDesc' sort by price; 'newest' shows recently listed items. Applies to keyword searches; for startUrls the URL's own sort is respected.",
            "default": "relevance"
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "number",
            "description": "Only return products at or above this price, in the site's currency (e.g. 5 means $5+ on aliexpress.com). Applied both as an AliExpress URL filter and a safety re-check on the parsed price. Leave empty for no minimum."
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "number",
            "description": "Only return products at or below this price, in the site's currency (e.g. 50 means up to $50 on aliexpress.com). Applied both as an AliExpress URL filter and a safety re-check on the parsed price. Leave empty for no maximum."
          },
          "freeShipping": {
            "title": "Free shipping only",
            "type": "boolean",
            "description": "When enabled, restricts the AliExpress search to products offering free shipping to the ship-to country. Default false.",
            "default": false
          },
          "choiceOnly": {
            "title": "Choice products only",
            "type": "boolean",
            "description": "Keep only products that carry the AliExpress Choice badge (faster delivery, buyer protection). Checked on every returned product, so results are exact. Default false.",
            "default": false
          },
          "excludeSponsored": {
            "title": "Skip sponsored results",
            "type": "boolean",
            "description": "Drop paid-placement (advertised) cards so only organic results are returned. Each record also carries an 'isSponsored' flag. Default false.",
            "default": false
          },
          "shipFrom": {
            "title": "Ships from",
            "enum": [
              "US",
              "CN",
              "GB",
              "DE",
              "ES",
              "FR",
              "IT",
              "NL",
              "PL",
              "RU",
              "BR",
              "AU",
              "CA",
              "MX",
              "KR",
              "JP",
              "TR",
              "SA",
              "AE"
            ],
            "type": "string",
            "description": "Only products shipped from this warehouse country (for example 'US' for fast local delivery, or 'CN'). Leave unset for any."
          },
          "minRating": {
            "title": "Minimum rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Drop products whose average star rating (0–5) is below this value, or whose rating is unknown. Useful to keep only well-reviewed products (e.g. 4.5 keeps 4.5★ and up). Filtered products are not billed. Leave empty to keep all ratings."
          },
          "minOrders": {
            "title": "Minimum orders sold",
            "minimum": 0,
            "type": "integer",
            "description": "Drop products with fewer than this many orders/sold, or whose orders count is unknown. Useful to surface proven sellers (e.g. 100 keeps items with 100+ sold). Filtered products are not billed. Leave empty to keep all."
          },
          "site": {
            "title": "AliExpress domain",
            "enum": [
              "aliexpress.com",
              "aliexpress.us",
              "de.aliexpress.com",
              "fr.aliexpress.com",
              "es.aliexpress.com",
              "it.aliexpress.com",
              "pt.aliexpress.com",
              "ru.aliexpress.com"
            ],
            "type": "string",
            "description": "Which AliExpress regional domain to search. Affects language and default currency of returned data. Use 'aliexpress.com' (global English) unless you need region-specific pricing. Default 'aliexpress.com'.",
            "default": "aliexpress.com"
          },
          "shipCountry": {
            "title": "Ship-to country",
            "type": "string",
            "description": "Two-letter ISO country code used as the ship-to country and the residential proxy country (e.g. 'US', 'GB', 'DE'). Affects shipping options and which prices AliExpress shows. Defaults to 'US'.",
            "default": "US"
          },
          "currency": {
            "title": "Currency",
            "enum": [
              "USD",
              "EUR",
              "GBP",
              "CAD",
              "AUD",
              "BRL",
              "PLN",
              "CHF",
              "SEK",
              "JPY",
              "KRW",
              "MXN",
              "AED",
              "SAR",
              "TRY"
            ],
            "type": "string",
            "description": "Show prices in this currency. Leave unset to let AliExpress choose from the ship-to country."
          },
          "language": {
            "title": "Language",
            "enum": [
              "en",
              "de",
              "fr",
              "es",
              "it",
              "pt",
              "ru",
              "nl",
              "pl",
              "tr",
              "ja",
              "ko"
            ],
            "type": "string",
            "description": "Language of titles and labels. Leave unset for AliExpress's default for the ship-to country."
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Optional. By default the Actor reads search pages over a fast HTTP route and only opens a browser for a page that route cannot read, using the cheapest working proxy. Set your own proxy group or URLs here only if you want every page loaded in a browser through your proxy.",
            "default": {
              "useApifyProxy": true
            }
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}