{
  "openapi": "3.0.1",
  "info": {
    "title": "AliExpress Product Search Scraper",
    "description": "Search AliExpress by keyword (or paste a search/category URL) and export product listing cards: title, price, original price, discount, rating, orders sold, store, image, and product URL. Filter by sort order, price range, free shipping, minimum rating, and minimum orders. Pay-per-event. MCP-ready.",
    "version": "1.0",
    "x-build-id": "ahOK0Oyq4UDItvxaN"
  },
  "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 opens the AliExpress search results page and collects every product listing card across pages. Leave empty if you instead provide startUrls. NOT a single product URL — this Actor searches and returns many products, it does not scrape one product page."
          },
          "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.",
            "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": "integer",
            "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": "integer",
            "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
          },
          "minRating": {
            "title": "Minimum rating",
            "minimum": 0,
            "maximum": 5,
            "type": "integer",
            "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 keeps 4★ 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"
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Residential proxies are strongly recommended — AliExpress blocks datacenter IPs. The Actor automatically prefers Apify residential (pinned to the ship-to country) when your account has it, and gracefully falls back to Apify datacenter when it does not — so leaving this at the default works on any plan. Override only if you have a specific proxy requirement.",
            "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
                  }
                }
              },
              "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}