{ "openapi": "3.0.1", "info": { "title": "Amazon Bestsellers Scraper + AI: Rising Products Only", "description": "First 25 product opportunities free. Amazon bestsellers: AI to find rising Amazon products you can still beat. Pay per qualified product. Amazon product research with AI. Demo, built-in list reader and own lists on any plan; the Store source Actor only on a plan that runs Store Actors.", "version": "0.1", "x-build-id": "BAU22l5Glf3q2RGcJ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/rich_minds~amazon-product-finder-ai/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-rich_minds-amazon-product-finder-ai", "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/rich_minds~amazon-product-finder-ai/runs": { "post": { "operationId": "runs-sync-rich_minds-amazon-product-finder-ai", "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/rich_minds~amazon-product-finder-ai/run-sync": { "post": { "operationId": "run-sync-rich_minds-amazon-product-finder-ai", "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": { "niches": { "title": "Niches or departments to scan", "type": "array", "description": "Plain words, e.g. kitchen, pet supplies: the Actor scans those departments' Movers & Shakers and New Releases (up to 3, named in the status). The live search reads Amazon's pages itself; if Amazon blocks that, it runs a Store Actor on your Apify plan — if your plan cannot run Store Actors, use `list` mode.", "items": { "type": "string" } }, "marketplace": { "title": "Amazon marketplace", "enum": [ "amazon.com", "amazon.co.uk", "amazon.de", "amazon.in", "amazon.ca", "amazon.co.jp" ], "type": "string", "description": "Where the niches above are read. Prices keep the marketplace's currency. A department Amazon names differently there is skipped — paste its list URL instead.", "default": "amazon.com" }, "goalDescription": { "title": "What are you looking for? (optional)", "type": "string", "description": "Your goal in plain words, e.g. private-label kitchen gadgets under $30 that a new listing can beat. The AI scores every product against it; with no niche or list URL, the departments it names are scanned for you. Empty = a general FBA-sourcing goal." }, "preset": { "title": "Start from a ready niche search (one click)", "enum": [ "custom", "kitchen-rising", "pet-new-releases", "home-bestsellers" ], "type": "string", "description": "Pick a niche and press Start: it fills the search fields you left empty and runs the live search (spend-capped by maxDiscoveryChargeUsd). Your own values always win. Custom = fill the fields yourself.", "default": "custom" }, "minScore": { "title": "Minimum score (0–100)", "minimum": 0, "maximum": 100, "type": "integer", "description": "The field that decides what you pay: product opportunities scoring below this are discarded and not charged. Raise it to pay only for the strongest matches, lower it to see more.", "default": 50 }, "maxQualified": { "title": "Max qualified product opportunities to output", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Hard cap on results — and the ceiling of what this Actor charges: at most this many × $0.0092 with AI on (× $0.0037 with AI off), e.g. 100 × $0.0092; the source's own spend has its cap right below. The best-scoring product opportunities are output first.", "default": 100 }, "maxDiscoveryChargeUsd": { "title": "Max source spend (USD)", "minimum": 0.01, "maximum": 1000, "type": "number", "description": "Hard cap on what the source Actor run may charge your account when the built-in reader is blocked and the Store Actor runs instead — $0.50 in the form and for an API or agent call that leaves it out, so a first real search can never cost more. The built-in reader costs nothing here. Raise it for bigger searches.", "default": 0.5 }, "enableAi": { "title": "AI assessment", "type": "boolean", "description": "Score each product opportunity against your goal, explain why, summarise it and generate text. On = $0.0092 per qualified product opportunity + AI tokens; off = $0.0037 (rule-based flags and scores only). Your first 5 product opportunities get live AI verdicts on any plan; every one with Apify model access or a paid own key.", "default": true }, "notifyEmail": { "title": "E-mail me the new product opportunities (optional)", "type": "string", "description": "After every run with at least one new product opportunity, the run's digest (how many are new, the top 10 with links) is e-mailed here through Apify's send-mail Actor. Schedule the run weekly (Actions → Schedule) and only the new product opportunities come to your inbox — no Slack or Zapier needed. Never sent for the free demo." }, "categoryUrls": { "title": "Your own Amazon list URLs", "type": "array", "description": "Best Sellers, New Releases, Movers & Shakers or Most Wished For URLs from any of 10 Amazon domains; a product on several lists is one row. They replace the niche search. The live search reads Amazon's pages itself; if Amazon blocks that, it runs a Store Actor on your Apify plan — if your plan cannot run Store Actors, use `list` mode.", "items": { "type": "string" } }, "minStars": { "title": "Minimum stars", "minimum": 0, "maximum": 5, "type": "number", "description": "Free filter: products rated below this are dropped before any AI or charge. A product with no rating yet (typical for New Releases) is kept. 0 = off.", "default": 0 }, "minReviews": { "title": "Minimum reviews", "minimum": 0, "type": "integer", "description": "Free filter: products with fewer reviews are dropped. Raise it to keep only proven demand. 0 = off.", "default": 0 }, "maxReviews": { "title": "Maximum reviews (the barrier)", "minimum": 0, "type": "integer", "description": "Free filter: products with more reviews are dropped — a listing with thousands of reviews is slow to beat. 1,500 is a common ceiling for a new private label. 0 = off.", "default": 0 }, "priceMin": { "title": "Minimum price", "minimum": 0, "type": "number", "description": "Free filter in the list's own currency (a product with no price is kept). 0 = off.", "default": 0 }, "priceMax": { "title": "Maximum price", "minimum": 0, "type": "number", "description": "Free filter in the list's own currency (a product with no price is kept). 0 = off.", "default": 0 }, "maxRank": { "title": "Only the top N ranks", "minimum": 0, "maximum": 100, "type": "integer", "description": "Free filter: ignore products ranked below this position on their list (the best rank counts when a product is on several lists). 0 = the whole list.", "default": 0 }, "excludeBrands": { "title": "Exclude brands", "type": "array", "description": "Brand names to skip, e.g. apple, anker. A product whose title contains one of them as a whole word is dropped before any AI or charge.", "items": { "type": "string" } }, "onlyNewOrRising": { "title": "Only new or rising products", "type": "boolean", "description": "Free filter for scheduled runs: keep a product only if it is new to this search's memory, climbed since the last run, or is on Movers & Shakers / New Releases.", "default": false }, "targetFlags": { "title": "Target flags (any of)", "type": "array", "description": "Only deliver products that have at least one of these flags, and rank those with more of them higher. Leave empty to keep everything. Use the flag names from the README's flag table, e.g. rising_rank, low_barrier (risingRank works too); an unknown name stops the run at once with the list of valid ones.", "items": { "type": "string" } }, "suppressionList": { "title": "Exclude list", "type": "array", "description": "Names, URLs or ids to never output. Suppressed product opportunities are skipped before any processing and never charged.", "items": { "type": "string" } }, "llmProvider": { "title": "AI model access", "enum": [ "apify", "byok" ], "type": "string", "description": "Apify (no keys) — the AI runs through Apify's built-in OpenRouter proxy; tokens are billed to your Apify account at OpenRouter's rates. My own key — use your OpenAI / Anthropic / Gemini / Groq key instead; a free-tier key assesses only a few product opportunities per run — expect 1–3 AI checks (2 calls at a time, one after a rate limit, then the 3 borderline product opportunities retried one by one) — and the rest keep their rule score; a paid Groq / Gemini key (billing on) assesses every product opportunity.", "default": "apify" }, "llmModel": { "title": "AI model", "type": "string", "description": "Leave empty for the default: anthropic/claude-haiku-4.5 on Apify; with your own key, the model of the key's provider (a Gemini key: google:gemini-3.5-flash-lite; Anthropic, OpenAI and Groq keys get their own). Apify mode takes an OpenRouter slug such as openai/gpt-4.1-mini; own-key mode takes provider:model, e.g. anthropic:claude-haiku-4-5-20251001." }, "llmApiKey": { "title": "Your API key (own-key mode only)", "type": "string", "description": "Required when AI model access is My own API key. Stored encrypted by Apify, never logged." }, "sendAlertsTo": { "title": "Send alerts to (Slack, Discord, Teams, Google Chat, Telegram or webhook)", "type": "string", "description": "Paste one or more URLs, one per line — the service is detected from the address: a Slack or Discord channel webhook, a Teams Workflows or Google Chat space webhook, your Telegram bot's send link (https://api.telegram.org/bot<token>/sendMessage?chat_id=@yourchannel) or any other https URL (Zapier, Make, n8n, your CRM), which gets the product opportunities as JSON. After every run with at least one new product opportunity, the digest (how many are new, the top 10 with links) is posted there. Never sent for the free demo. Headers, batching and signing: Delivery details (advanced)." }, "dedupeAcrossRuns": { "title": "Never output the same product opportunity twice", "type": "boolean", "description": "Remembers every product opportunity you were charged for (in a named key-value store on your account) and skips it in future runs.", "default": true }, "dedupeTtlDays": { "title": "Deliver a product opportunity again after (days)", "minimum": 0, "maximum": 3650, "type": "integer", "description": "How long a delivered product opportunity stays remembered. 0 = never deliver or charge it again. A number of days lets a product opportunity that comes back (a seasonal peak, a relisted item) reach you again after that many days — charged again as a new product opportunity.", "default": 0 }, "sourceMode": { "title": "Where do the product opportunities come from?", "enum": [ "actor", "dataset", "list" ], "type": "string", "description": "actor — read the Amazon list pages with the built-in reader; where Amazon blocks it, run amazon-scraper/amazon-bestsellers-scraper on your account instead (billed separately). dataset — an existing Apify dataset. list — records you paste in. The mode you choose always runs as chosen; only the untouched sample next to a search you typed switches to the live search (spend-capped). {} over the API runs the free demo — nothing charged.", "default": "actor" }, "ownSource": { "title": "Read the source site directly (no Store Actor)", "type": "boolean", "description": "On (default): when this Actor reads its source site itself, no second Store Actor runs on your account and no second bill appears — it works on every Apify plan. If the direct read is blocked, or the run needs something only the Store Actor returns, the Store Actor runs as before. Off: always the Store Actor.", "default": true }, "datasetId": { "title": "Dataset", "type": "string", "description": "Only for dataset mode. Pick the dataset so the Actor is granted read access to it." }, "itemsList": { "title": "Product rows to process", "type": "array", "description": "Only for list mode. JSON array of rows in the source's shape: title (or name), asin, link, price, stars, reviewsCount, position, categoryUrl. Rows of one ASIN are merged." }, "subcategoryLevel": { "title": "Subcategory depth", "minimum": 0, "maximum": 10, "type": "integer", "description": "Affects what you pay: how many subcategory levels the source also scans below each URL. 0 = only the list you gave (up to 50 rows ≈ $0.10 at the source's $0.002 per row); every level multiplies the rows. Always capped by Max source spend.", "default": 0 }, "nextPage": { "title": "Also read page 2 (ranks 51–100)", "type": "boolean", "description": "Affects what you pay: on = both pages of each list (up to 100 rows ≈ $0.20 per URL at the source's $0.002 per row), off = ranks 1–50 only. Capped by Max source spend.", "default": false }, "webhookUrl": { "title": "Webhook URL (optional)", "type": "string", "description": "Qualified product opportunities are POSTed here as JSON (Zapier, Make, n8n, your CRM). For Google Sheets / Slack you can also use Apify's built-in Integrations tab. Stored encrypted — Zapier / Make hook URLs carry their secret in the path." }, "webhookSecret": { "title": "Webhook signing secret (optional)", "type": "string", "description": "Any random string. Every webhook POST then carries X-Signature: sha256=<HMAC-SHA256 of the raw body with this secret>, so your endpoint can verify it came from this Actor. Stored encrypted by Apify, never logged." }, "dedupeStoreName": { "title": "Dedupe store name", "type": "string", "description": "Key-value store used for cross-run memory. Left at the default, the memory is kept per search (source and search terms): rewording goalDescription keeps it, so a scheduled run never re-delivers what you already have, and another search starts its own list. Running it for several clients on one account, type one name per client.", "default": "amazon-product-finder-ai-seen" }, "discoveryTimeoutSecs": { "title": "Source run timeout, seconds (API only)", "minimum": 60, "maximum": 86400, "type": "integer", "description": "API only — hidden on the form. How long the source Store Actor may run before its partial results are used. Raise it when the status says the source stopped early.", "default": 3600 }, "slackWebhookUrl": { "title": "Slack webhook URL (API only)", "type": "string", "description": "API only — hidden on the form, where sendAlertsTo takes it. Slack incoming-webhook URL for the digest." }, "discordWebhookUrl": { "title": "Discord webhook URL (API only)", "type": "string", "description": "API only — hidden on the form, where sendAlertsTo takes it. Discord channel webhook URL for the digest." }, "teamsWebhookUrl": { "title": "Microsoft Teams webhook URL (API only)", "type": "string", "description": "API only — hidden on the form, where sendAlertsTo takes it. Teams Workflows webhook URL for the digest." }, "googleChatWebhookUrl": { "title": "Google Chat webhook URL (API only)", "type": "string", "description": "API only — hidden on the form, where sendAlertsTo takes it. Google Chat space webhook URL for the digest." }, "telegramUrl": { "title": "Telegram sendMessage link (API only)", "type": "string", "description": "API only — hidden on the form, where sendAlertsTo takes it. The bot's sendMessage link with its chat_id." }, "aiCandidateMultiplier": { "title": "AI candidate pool (× max qualified) (API only)", "minimum": 1, "maximum": 5, "type": "integer", "description": "API only — hidden on the form. How many of the best rule-scored candidates get the AI pass, as a multiple of Max qualified. Higher = more thorough, slower, more tokens.", "default": 2 }, "webhookBatchSize": { "title": "Webhook batch size (API only)", "minimum": 1, "maximum": 500, "type": "integer", "description": "API only — hidden on the form. 1 = one POST per product opportunity the moment it is ready. Higher = one POST per N product opportunities.", "default": 1 }, "maxToProcess": { "title": "Max candidates to process (API only)", "minimum": 1, "maximum": 20000, "type": "integer", "description": "API only — hidden on the form. Upper bound on how many product opportunities are scored in one run (controls run time). Default = 3 × max qualified." }, "discoveryInput": { "title": "Source Actor input (API only)", "type": "object", "description": "API only — hidden on the form. Only for actor mode, optional: extra input passed to the source Actor as-is; it overrides the fields above (e.g. its own urls). Normally leave it empty and use Amazon list or category URLs. The live search runs that Store Actor on your Apify plan — if your plan cannot run Store Actors, paste your own rows in list mode (any plan); dataset only for a dataset you already have." }, "webhookHeaders": { "title": "Webhook headers (API only)", "type": "object", "description": "API only — hidden on the form. Extra HTTP headers for the webhook, e.g. {\"Authorization\": \"Bearer …\"}. Stored encrypted by Apify, never logged." }, "discoveryActorId": { "title": "Source Actor (API only)", "type": "string", "description": "API only — hidden on the form. Actor used in actor mode. Any Actor whose output has the fields listed in the README works.", "default": "amazon-scraper/amazon-bestsellers-scraper" }, "autoSwitchToLive": { "title": "Typed search next to the sample starts the live search (API only)", "type": "boolean", "description": "API only — hidden on the form. On (default): search terms typed next to the untouched sample records start the live search (spend-capped; OUTPUT.switchedToLive names them). Off: the mode you send is the mode that runs — the sample stays the free demo and the status names the terms it did not search. API pipelines that must never start a paid read on their own: send false.", "default": true }, "historyDatasetName": { "title": "Keep a running log (dataset name) (API only)", "type": "string", "description": "API only — hidden on the form. Optional. Type a name (e.g. amazon-product-finder-ai-seen-log) and every run appends its new product opportunities with the date to that named dataset on your account — one list across months to connect to Google Sheets or your BI tool once. Empty = off. Costs nothing extra.", "default": "" } } }, "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 } } } } } } } } } }