{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Product Scraper - Prices, ASIN, BSR & Reviews",
    "description": "Amazon product scraper for prices, ASINs, ratings, review counts, BSR, availability, sellers, images, and rank alerts across 19 marketplaces. Built for seller research, competitor monitoring, price tracking, and MCP connector alerts.",
    "version": "2.2",
    "x-build-id": "5PGnb04ylbRDXSKLP"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/harvestlab~amazon-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-harvestlab-amazon-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/harvestlab~amazon-scraper/runs": {
      "post": {
        "operationId": "runs-sync-harvestlab-amazon-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/harvestlab~amazon-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-harvestlab-amazon-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 Query",
            "type": "string",
            "description": "Search keyword(s) to find products on Amazon (e.g., 'iPhone 15 Pro', 'mechanical keyboard', 'air fryer')."
          },
          "query": {
            "title": "Search Query (CLI alias)",
            "type": "string",
            "description": "CLI alias for searchQuery. Hidden from Console form."
          },
          "q": {
            "title": "Search Query (CLI alias)",
            "type": "string",
            "description": "CLI alias for searchQuery. Hidden from Console form."
          },
          "search": {
            "title": "Search Query (CLI alias)",
            "type": "string",
            "description": "CLI alias for searchQuery. Hidden from Console form."
          },
          "keyword": {
            "title": "Search Query (CLI alias)",
            "type": "string",
            "description": "CLI alias for searchQuery. Hidden from Console form."
          },
          "searchTerm": {
            "title": "Search Query (CLI alias)",
            "type": "string",
            "description": "CLI alias for searchQuery. Hidden from Console form."
          },
          "productUrls": {
            "title": "Product URLs",
            "type": "array",
            "description": "Direct Amazon product URLs to scrape (alternative to search). Example: `https://www.amazon.com/dp/B0C7BZR4DC` (the B0C7BZR4DC is the ASIN). Overrides search query if both are provided.",
            "items": {
              "type": "string"
            }
          },
          "urls": {
            "title": "Product URLs (CLI alias)",
            "type": "array",
            "description": "CLI alias for productUrls. Hidden from Console form.",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "title": "Product URLs (CLI alias)",
            "type": "array",
            "description": "CLI alias for productUrls. Hidden from Console form.",
            "items": {
              "type": "string"
            }
          },
          "amazonDomain": {
            "title": "Amazon Domain",
            "enum": [
              "amazon.com",
              "amazon.ca",
              "amazon.com.mx",
              "amazon.com.br",
              "amazon.co.uk",
              "amazon.de",
              "amazon.fr",
              "amazon.es",
              "amazon.it",
              "amazon.nl",
              "amazon.pl",
              "amazon.se",
              "amazon.co.jp",
              "amazon.in",
              "amazon.com.au",
              "amazon.ae",
              "amazon.sa",
              "amazon.sg",
              "amazon.com.tr"
            ],
            "type": "string",
            "description": "Which Amazon country marketplace to scrape. Different marketplaces have different ASINs, pricing in local currency, and product availability.",
            "default": "amazon.com"
          },
          "domain": {
            "title": "Amazon Domain (CLI alias)",
            "type": "string",
            "description": "CLI alias for amazonDomain. Hidden from Console form."
          },
          "country_domain": {
            "title": "Amazon Domain (CLI alias)",
            "type": "string",
            "description": "CLI alias for amazonDomain. Hidden from Console form."
          },
          "maxProducts": {
            "title": "Max Products",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum number of products to scrape. Amazon shows ~20 per search page. Start with 10 to test before running larger jobs. Capped at 100 for PPE bill safety.",
            "default": 10
          },
          "maxItems": {
            "title": "Max Items (alias for Max Products)",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Alternative name for Max Products - accepts the same values. Use either maxProducts or maxItems."
          },
          "sortBy": {
            "title": "Sort By",
            "enum": [
              "relevance",
              "price_low",
              "price_high",
              "avg_review",
              "newest"
            ],
            "type": "string",
            "description": "Sort order for search results. 'Relevance' (default) is Amazon's algorithmic ranking mixing sales, reviews, and keyword match. 'Price Low/High' sorts by current list price. 'Avg. Customer Review' ranks by star rating (biased toward items with many reviews). 'Newest Arrivals' surfaces recently listed products - best for trend-spotting but noisy. Only applies when using a search query, not direct product URLs.",
            "default": "relevance"
          },
          "fetchDetails": {
            "title": "Fetch Product Details",
            "type": "boolean",
            "description": "Fetch individual product detail pages to enrich results with brand, availability, description, features, and seller info. Adds ~2-3s per product but significantly improves data quality. Keep false for fast search-page-only first runs.",
            "default": false
          },
          "includeDetails": {
            "title": "Include Product Details (alias)",
            "type": "boolean",
            "description": "CLI alias for fetchDetails. Hidden from Console form."
          },
          "trackBestsellerRank": {
            "title": "Track Best Sellers Rank (time-series)",
            "type": "boolean",
            "description": "Persist each product's Best Sellers Rank across runs and emit rank_now / rank_previous / rank_change / rank_peak / rank_movement fields on every scraped item. Pair with Apify scheduler to build a BSR history per ASIN. Forces fetchDetails=true. Adds a per-ASIN `rank-tracked` charge ($0.01) on top of the normal product-scraped charge. When combined with Enable AI Analysis, the AI report switches to a rank-movement narrative (why products are climbing or falling). First run establishes the baseline; second run onward emits deltas.",
            "default": false
          },
          "alertWebhookUrl": {
            "title": "BSR Alert Webhook URL (optional)",
            "type": "string",
            "description": "POST a compact JSON payload to this URL whenever a tracked ASIN's absolute rank_change crosses the threshold below. Turns the actor into a real-time BSR alert service - pipe into Slack/Discord/Zapier/Make/n8n/your own endpoint. Fire-and-forget: 5s timeout, 1 retry on failure, webhook errors never fail the run. Only fires on second-run-onward (needs a prior snapshot for deltas). Setting this automatically enables trackBestsellerRank. Adds an `alert-dispatched` charge ($0.002) per successful webhook. Leave empty to disable."
          },
          "outputConnectors": {
            "title": "MCP Output Connectors",
            "maxItems": 5,
            "uniqueItems": true,
            "type": "array",
            "description": "Optional MCP connectors for BSR rank alerts. Choose Slack, Notion, GitHub, Sheets, CRM, or another compatible connector. When a rank alert qualifies, the actor sends a compact message plus structured payload through each connector. Connector failures never fail the scrape. Billed at $0.002 per successful connector dispatch."
          },
          "connectorAlertTarget": {
            "title": "Connector Target",
            "type": "string",
            "description": "Optional connector destination such as a Slack channel, Notion database ID, sheet name, table, or CRM list. Leave empty when the selected connector already has a default target."
          },
          "alertRankThreshold": {
            "title": "BSR Alert Rank Threshold",
            "minimum": 1,
            "maximum": 1000000,
            "type": "integer",
            "description": "Minimum absolute rank_change required to fire a webhook. Default 50 means a climb from #200 to #150 (or a drop from #100 to #151) triggers an alert. Lower = more alerts, higher = noisier movers only. Only applies when alertWebhookUrl is set.",
            "default": 50
          },
          "enableAiAnalysis": {
            "title": "Enable AI Analysis",
            "type": "boolean",
            "description": "Run AI-powered competitive pricing analysis on scraped products. Requires an LLM API key from one of the providers below (OpenRouter is cheapest at ~$0.001/run). When Track Best Sellers Rank is also ON, the AI switches to a rank-movement report (narrates why products are climbing/falling) instead of the default pricing analysis.",
            "default": false
          },
          "llmProvider": {
            "title": "LLM Provider",
            "enum": [
              "openrouter",
              "anthropic",
              "google",
              "openai",
              "ollama"
            ],
            "type": "string",
            "description": "Which AI provider to use for analysis.",
            "default": "openrouter"
          },
          "openrouterApiKey": {
            "title": "OpenRouter API Key",
            "type": "string",
            "description": "API key for OpenRouter (required if LLM Provider = OpenRouter). Get one at https://openrouter.ai/keys. Or set the OPENROUTER_API_KEY env var on the actor."
          },
          "anthropicApiKey": {
            "title": "Anthropic API Key",
            "type": "string",
            "description": "API key for Anthropic Claude (required if LLM Provider = Anthropic). Get one at https://console.anthropic.com/settings/keys. Or set the ANTHROPIC_API_KEY env var on the actor."
          },
          "googleApiKey": {
            "title": "Google AI API Key",
            "type": "string",
            "description": "API key for Google AI / Gemini (required if LLM Provider = Google AI). Get one at https://aistudio.google.com/app/apikey. Or set the GOOGLE_API_KEY env var on the actor."
          },
          "openaiApiKey": {
            "title": "OpenAI API Key",
            "type": "string",
            "description": "API key for OpenAI (required if LLM Provider = OpenAI). Get one at https://platform.openai.com/api-keys. Or set the OPENAI_API_KEY env var on the actor."
          },
          "ollamaBaseUrl": {
            "title": "Ollama Base URL",
            "type": "string",
            "description": "Base URL for a self-hosted Ollama server (only used if LLM Provider = Ollama). Default: http://localhost:11434. Install Ollama at https://ollama.com/download."
          },
          "llmModel": {
            "title": "LLM Model",
            "type": "string",
            "description": "Specific model to use. Leave empty for the provider default (google/gemini-2.0-flash-001 for OpenRouter, claude-sonnet-4-20250514 for Anthropic, gemini-2.0-flash for Google AI, gpt-4o-mini for OpenAI, llama3.1 for Ollama)."
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Proxy settings. Residential proxies recommended for Amazon. Tip: for consistent pricing/currency, match the proxy country to your target amazonDomain (e.g. `apifyProxyCountry=US` for amazon.com, `DE` for amazon.de, `JP` for amazon.co.jp) - Amazon localizes prices by visitor IP."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}