{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Product Search Scraper: Rank, Price & Details",
    "description": "Search Amazon by keyword or URL across 18 marketplaces and see where every product ranks: page position, organic rank and sponsored flag, plus price, rating and reviews. Add detail pages for brand, Best Sellers Rank, bullets, images and seller.",
    "version": "1.3",
    "x-build-id": "KTDPBBmkRKhxsPP7E"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/khadinakbar~amazon-product-search-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-khadinakbar-amazon-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~amazon-product-search-scraper/runs": {
      "post": {
        "operationId": "runs-sync-khadinakbar-amazon-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~amazon-product-search-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-khadinakbar-amazon-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": "A single free-text Amazon search term, e.g. 'wireless earbuds' or 'stainless steel water bottle'. The actor runs this as an Amazon search and returns matching products. Defaults to 'wireless earbuds'. NOT an Amazon product (/dp/) URL — for keyword + URL batches use searchQueries or startUrls instead."
          },
          "searchQueries": {
            "title": "Search keywords (bulk)",
            "type": "array",
            "description": "A list of search terms to run in one job, e.g. ['gaming mouse','mechanical keyboard']. Each term is searched independently and results share one dataset. Use this instead of searchQuery when you need several keywords. Leave empty if you only need one keyword or are using startUrls.",
            "items": {
              "type": "string"
            }
          },
          "startUrls": {
            "title": "Amazon search / category URLs",
            "type": "array",
            "description": "Amazon search-result or category page URLs to scrape directly, e.g. 'https://www.amazon.com/s?k=running+shoes'. Use this when you already have a filtered Amazon URL or a category/browse-node page. The marketplace is auto-detected from each URL's domain. Single product (/dp/ or /gp/product/) URLs are rejected — this actor takes search/category pages, not individual ASINs.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "country": {
            "title": "Amazon marketplace",
            "enum": [
              "US",
              "UK",
              "DE",
              "FR",
              "CA",
              "ES",
              "IT",
              "JP",
              "AU",
              "IN",
              "MX",
              "BR",
              "NL",
              "SE",
              "PL",
              "TR",
              "AE",
              "SG"
            ],
            "type": "string",
            "description": "Which Amazon marketplace to search when you pass a keyword (e.g. 'US' → amazon.com, 'UK' → amazon.co.uk, 'DE' → amazon.de). Controls the domain, currency, and proxy country. Defaults to 'US'. Ignored for startUrls, where the marketplace is read from each URL.",
            "default": "US"
          },
          "maxResults": {
            "title": "Max products",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum number of products to return across the whole run (the hard cost cap — you are charged per product, never more than this). Accepts 1 to 1000. Defaults to 50. Pagination stops once this many products are collected.",
            "default": 50
          },
          "enrichDetails": {
            "title": "Enrich with product detail pages",
            "type": "boolean",
            "description": "When true (default), each product's /dp/ detail page is also fetched to add brand, feature bullets, description, all images, best-sellers rank, buybox seller, breadcrumbs, and variations. Set to false for a faster, cheaper search-only run that returns just the SERP fields (price, rating, rank). Detail enrichment is what distinguishes this actor from a plain SERP scraper.",
            "default": true
          },
          "sortBy": {
            "title": "Sort order",
            "enum": [
              "relevance",
              "priceAsc",
              "priceDesc",
              "avgCustomerReview",
              "newest"
            ],
            "type": "string",
            "description": "Amazon result sort order applied to keyword searches: 'relevance' (default), 'priceAsc', 'priceDesc', 'avgCustomerReview', or 'newest'. Maps to Amazon's own sort parameters. Ignored for startUrls that already include a sort.",
            "default": "relevance"
          },
          "includeSponsored": {
            "title": "Include sponsored products",
            "type": "boolean",
            "description": "When true (default), sponsored/ad placements are included and flagged with isSponsored=true so you can tell ads from organic results. Set to false to return organic results only. Organic rank is always tracked separately in the organicRank field.",
            "default": true
          },
          "minPrice": {
            "title": "Minimum price",
            "minimum": 0,
            "type": "number",
            "description": "Only return products listed at or above this price, in the store's own currency (for example dollars on the US store). Products with no listed price are skipped when a price filter is on. You are only charged for products that are returned. Leave empty for no minimum."
          },
          "maxPrice": {
            "title": "Maximum price",
            "minimum": 0,
            "type": "number",
            "description": "Only return products listed at or below this price, in the store's own currency. Products with no listed price are skipped when a price filter is on. You are only charged for products that are returned. Leave empty for no maximum."
          },
          "minRating": {
            "title": "Minimum star rating",
            "minimum": 0,
            "maximum": 5,
            "type": "number",
            "description": "Only return products rated at least this many stars, from 0 to 5 (for example 4 for '4 stars and up'). Products with no rating are skipped when this is set. Leave empty or 0 for no rating filter."
          },
          "primeOnly": {
            "title": "Prime products only",
            "type": "boolean",
            "description": "When on, only products Amazon marks as Prime-eligible are returned. Amazon does the filtering, so it works on the US store; on other stores the run stops with a clear message (paste a search link that already has Amazon's Prime filter applied instead). Default is off (all products).",
            "default": false
          },
          "maxResultsPerQuery": {
            "title": "Max products per keyword or URL",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "Optional cap on how many products each keyword or URL can return, so one popular keyword cannot use up the whole budget. 'Max products' still limits the whole run. Leave empty for no per-keyword limit. Filters (price, rating, Prime) look only at the search pages the Actor reads (see 'Max search pages'), so a tight filter can return fewer products; raise 'Max search pages' to look deeper."
          },
          "maxSearchPages": {
            "title": "Max search pages per seed",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of Amazon search-result pages to paginate through per keyword/URL before stopping (each page is ~16–60 products). Accepts 1 to 20. Defaults to 5. Lower this to cap how deep into the rankings the run goes; maxResults still caps the total.",
            "default": 5
          },
          "proxyConfiguration": {
            "title": "Proxy configuration",
            "type": "object",
            "description": "Proxy settings. Amazon blocks many datacenter IPs, so residential proxies are strongly recommended. Leave at the default (Apify Proxy on) and the actor automatically prefers residential and falls back to datacenter. You can explicitly select the Apify UNBLOCKER group for a fully Unblocker-routed run; it is billed separately by Apify and the actor accepts its valid octet-stream HTML response. Let Unblocker choose country unless the request requires a specific locale.",
            "default": {
              "useApifyProxy": true
            }
          },
          "routeMode": {
            "title": "Request routing (advanced)",
            "enum": [
              "auto",
              "unlocker",
              "pool",
              "apify"
            ],
            "type": "string",
            "description": "Automatic routing picks the cheapest route that works and escalates only when Amazon blocks a request. Force one route only to compare them.",
            "default": "auto"
          },
          "proxyTier": {
            "title": "Proxy cost mode",
            "enum": [
              "auto",
              "residential",
              "datacenter"
            ],
            "type": "string",
            "description": "Which proxy type to use first for product detail pages when you have not chosen a proxy yourself. 'auto' (default) starts with cheaper datacenter addresses and switches a request to residential addresses only when Amazon blocks it, which lowers cost. 'residential' always uses residential addresses. Search pages always use residential addresses in the store's own country.",
            "default": "auto"
          },
          "costGuard": {
            "title": "Detail-page cost guard",
            "enum": [
              "auto",
              "on",
              "off"
            ],
            "type": "string",
            "description": "Limits how many product detail pages may use expensive residential addresses in one run. 'auto' (default) applies the limit only when the Actor owner pays the platform usage; then, if Amazon blocks the cheaper addresses, products beyond the limit are returned as search rows without detail data (marked detail_skipped_cost_guard, run ends PARTIAL) and you are not charged the detail fee for them. 'off' never limits. 'on' always limits.",
            "default": "auto"
          },
          "useUnblockerFallback": {
            "title": "Retry classified blocks through Apify Unblocker",
            "type": "boolean",
            "description": "When true (default), the actor retries up to two retry-exhausted Amazon search seeds through Apify Unblocker only when the native route returned zero products with a 403, 429, 5xx, challenge, or soft-block signal. This is a bounded reliability fallback, not a promise to bypass every Amazon protection. Apify bills Unblocker usage separately; set false to use only the selected proxy route.",
            "default": 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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}