{
  "openapi": "3.0.1",
  "info": {
    "title": "Amazon Scraper – Prices, BSR Time-Series & AI",
    "description": "Scrape 11 Amazon marketplaces at $0.005/product. Unique: cross-run BSR time-series + real-time webhook alerts to Slack/Zapier/n8n. AI pricing analysis via 5 LLMs. Beats $39/mo rank-alert SaaS by 200×.",
    "version": "2.0",
    "x-build-id": "ktBYgmrudEZqO6Fc3"
  },
  "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.co.uk",
              "amazon.de",
              "amazon.fr",
              "amazon.it",
              "amazon.es",
              "amazon.ca",
              "amazon.co.jp",
              "amazon.com.au",
              "amazon.nl",
              "amazon.in"
            ],
            "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": 500,
            "type": "integer",
            "description": "Maximum number of products to scrape. Amazon shows ~20 per search page. Start with 25 to test before running larger jobs.",
            "default": 25
          },
          "maxItems": {
            "title": "Max Items (alias for Max Products)",
            "minimum": 1,
            "maximum": 500,
            "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. Set to false for fast search-page-only scraping.",
            "default": true
          },
          "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."
          },
          "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. 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 (openrouter.ai). Required if using OpenRouter provider."
          },
          "anthropicApiKey": {
            "title": "Anthropic API Key",
            "type": "string",
            "description": "API key for Anthropic Claude (console.anthropic.com). Required if using Anthropic provider."
          },
          "googleApiKey": {
            "title": "Google AI API Key",
            "type": "string",
            "description": "API key for Google AI (Gemini). Get one at aistudio.google.com/app/apikey"
          },
          "openaiApiKey": {
            "title": "OpenAI API Key",
            "type": "string",
            "description": "API key from platform.openai.com (required if using OpenAI provider)"
          },
          "ollamaBaseUrl": {
            "title": "Ollama Base URL",
            "type": "string",
            "description": "Base URL for Ollama API. Default: http://localhost:11434"
          },
          "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}