{ "openapi": "3.0.1", "info": { "title": "Amazon Keyword Rank Tracker: Organic & Sponsored", "description": "Track where your products rank on Amazon search for your keywords: organic and sponsored place, page, who outranks you, and changes since the last run, in 22 marketplaces. Plus each keyword's top results and competition. From $2 per 1,000 pages; compact JSON for AI agents.", "version": "0.1", "x-build-id": "8ccmTU7jTvs1h1XPZ" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanpull~amazon-keyword-rank-tracker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanpull-amazon-keyword-rank-tracker", "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/cleanpull~amazon-keyword-rank-tracker/runs": { "post": { "operationId": "runs-sync-cleanpull-amazon-keyword-rank-tracker", "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/cleanpull~amazon-keyword-rank-tracker/run-sync": { "post": { "operationId": "run-sync-cleanpull-amazon-keyword-rank-tracker", "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": { "keywords": { "title": "Keywords", "type": "array", "description": "Search terms, one per line, as shoppers type them into Amazon.", "items": { "type": "string" } }, "asins": { "title": "Your products (ASINs)", "type": "array", "description": "Optional. ASINs or Amazon product URLs whose rank you want for every keyword: organic place, sponsored place, page, and who ranks above. Leave empty to get only each keyword's results.", "items": { "type": "string" } }, "marketplace": { "title": "Marketplace", "type": "string", "description": "A country code or domain: US, GB (or UK), DE, FR, IT, ES, CA, MX, BR, JP, IN, AU, NL, SE, PL, BE, TR, AE, SA, SG, EG, IE. Outside the US, pages are read from that country (residential add-on).", "default": "US" }, "maxResults": { "title": "Organic results to scan", "minimum": 1, "maximum": 350, "type": "integer", "description": "How deep to look for your products: organic results read per keyword (pages are followed, up to 7; Amazon shows 16 to 48 organic results a page depending on the category).", "default": 48 }, "stopWhenFound": { "title": "Stop once all products are found", "type": "boolean", "description": "Stop reading pages for a keyword once every product above has been found organically (fewer pages, lower cost).", "default": true }, "sponsored": { "title": "Sponsored places", "type": "boolean", "description": "Also record ad (sponsored) places. In the US, Amazon shows ads only to home-network visitors, so pages are read through residential addresses (add-on per page). Off: organic ranks only, cheaper.", "default": true }, "samples": { "title": "Readings per keyword", "minimum": 1, "maximum": 3, "type": "integer", "description": "Read each search 1 to 3 times on fresh sessions and report the median rank, with the range. Organic ranks move by 1 to 3 places between readings; 3 readings steady them (each reading is billed as its pages).", "default": 1 }, "resultRows": { "title": "One row per search result", "type": "boolean", "description": "Also return every result card read (position, organic or sponsored place, price, rating, reviews, badges, bought in past month) as its own row.", "default": false }, "changesOnly": { "title": "Changes only", "type": "boolean", "description": "Return only product ranks that changed since the last run with the same monitor name. Pages read are still billed; unchanged ranks are free. Schedule it daily.", "default": false }, "monitorName": { "title": "Monitor name", "type": "string", "description": "Runs with the same name compare against each other.", "default": "default" }, "rankChangeMin": { "title": "Smallest rank move", "minimum": 1, "maximum": 100, "type": "integer", "description": "A rank move counts as a change from this many places. Amazon reshuffles results by 1 to 3 places between two reads of the same page.", "default": 3 }, "rankChangePercent": { "title": "Smallest rank move (% of rank)", "minimum": 0, "maximum": 100, "type": "integer", "description": "Deeper ranks move more between reads, so a move must also be this share of the earlier rank: at 25%, rank 4 needs 3 places (the minimum above), rank 21 needs 6, rank 40 needs 10. 0 uses only the minimum above.", "default": 25 }, "maxRunCostUsd": { "title": "Max cost per run (USD)", "minimum": 0.01, "maximum": 1000, "type": "number", "description": "Optional. A keyword is read only when what this run has charged, plus the most that keyword could cost, stays within this amount. For scheduled runs and tasks, where no spending limit may be set." }, "maxItems": { "title": "Max rows", "minimum": 1, "type": "integer", "description": "Optional. Stop after this many rows." }, "fields": { "title": "Only these fields", "type": "array", "description": "Optional. Keep only these fields, for example [\"keyword\", \"asin\", \"organicRank\", \"sponsoredRank\"].", "items": { "type": "string" } }, "providerFallback": { "title": "Provider fallback", "type": "boolean", "description": "Off by default. When Amazon refuses a keyword on every proxy, read its search results through CleanPull's marketplace data service instead (1 to 5 minutes). Costs $0.015 per keyword plus $0.003 per result record (up to Max results records), instead of the page price: about $0.16 per keyword at 48 results. It gives organic places only, no sponsored places. Only keywords Amazon refused use it. Off: a refused keyword fails and costs nothing.", "default": false }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional. The actor picks proxies itself (in-country addresses outside the US, residential for ads in the US)." } } }, "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 } } } } } } } } } }