{ "openapi": "3.0.1", "info": { "title": "Marketplace Search Scanner: Amazon, eBay, Etsy", "description": "For any keyword, see the market on Amazon, eBay, Etsy, Walmart, Target and Best Buy: every listing with price, seller and reviews, plus price percentiles, seller concentration, review depth and new entrants since your last run. Only your Apify account needed.", "version": "0.3", "x-build-id": "tdI7LdUkfpoLyPBjM" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/cleanpull~marketplace-search-scanner/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-cleanpull-marketplace-search-scanner", "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~marketplace-search-scanner/runs": { "post": { "operationId": "runs-sync-cleanpull-marketplace-search-scanner", "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~marketplace-search-scanner/run-sync": { "post": { "operationId": "run-sync-cleanpull-marketplace-search-scanner", "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.", "items": { "type": "string" } }, "sources": { "title": "Marketplaces", "type": "array", "description": "Where to search. Amazon is read from its search page. eBay, Etsy, Walmart, Target and Best Buy come through CleanPull's marketplace data service (nothing to set up): each search takes 1 to 5 minutes, and the keywords of a run are searched together.", "items": { "type": "string", "enum": [ "amazon", "ebay", "etsy", "walmart", "target", "bestbuy" ], "enumTitles": [ "Amazon", "eBay (ebay.com)", "Etsy", "Walmart", "Target", "Best Buy" ] }, "default": [ "amazon" ] }, "amazonMarketplaces": { "title": "Amazon marketplaces", "type": "array", "description": "Country codes or domains, one per line: US, GB, DE, FR, IT, ES, CA, MX, BR, JP, IN, AU, NL, SE, PL, BE, TR, AE, SA, SG, EG, IE. Empty: US. Outside the US, pages are read from that country (residential add-on).", "items": { "type": "string" } }, "maxResults": { "title": "Results per search", "minimum": 1, "maximum": 200, "type": "integer", "description": "Listings read per keyword and marketplace, in the order the marketplace shows them. Amazon: organic results (16 to 48 a page, up to 7 pages), plus the ads shown among them. Other marketplaces: up to this many results, each billed as a provider record.", "default": 48 }, "includeAds": { "title": "Amazon sponsored results", "type": "boolean", "description": "Also read Amazon's ads (sponsored listings). In the US, Amazon shows ads only to home-network visitors, so pages are read through residential addresses (add-on per page). Off: organic results only, cheaper.", "default": true }, "ebayFixedPriceOnly": { "title": "eBay fixed price only", "type": "boolean", "description": "Leave auctions out of the listings. Either way, auctions are left out of the price figures, since a current bid is not a selling price. Auctions read are still provider records.", "default": false }, "listingRows": { "title": "One row per listing", "type": "boolean", "description": "Return every listing read as its own row. Off: only the keyword summaries (and changes), cheaper.", "default": true }, "watchlistName": { "title": "Watchlist name", "type": "string", "description": "Runs with the same name compare against each other: new entrants, new sellers, listings that left the top, and price-band moves.", "default": "default" }, "changesOnly": { "title": "Changes only", "type": "boolean", "description": "Return only change rows (and the listings of new entrants). The first run of a watchlist returns its summaries as the baseline. Amazon pages and provider records read are still billed; unchanged searches deliver nothing else. Schedule it daily or weekly.", "default": false }, "newEntrantTop": { "title": "Watch the top", "minimum": 1, "maximum": 100, "type": "integer", "description": "New entrants and listings that left are counted in the top this many organic results, at most half the results read. A new entrant is a listing no earlier run saw anywhere in the results read (in the last 60 days) that is still in the top on the next run: one-off appearances and listings moving up from below do not count. A listing counts as gone only after 2 runs in a row without it.", "default": 24 }, "priceMoveMinPercent": { "title": "Smallest price-band move (%)", "minimum": 0, "maximum": 100, "type": "integer", "description": "The median or a quartile price must move this much from the baseline, in the same direction on 2 runs in a row, to count as a price-band move. Result sets differ between reads, so small or one-off moves are noise.", "default": 10 }, "maxRunCostUsd": { "title": "Max cost per run (USD)", "minimum": 0.01, "maximum": 1000, "type": "number", "description": "Optional. A search starts only when what this run has charged, plus the most that search 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\", \"source\", \"title\", \"price\", \"seller\"].", "items": { "type": "string" } }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Optional, Amazon only. The actor picks proxies itself (in-country addresses outside the US, residential for ads in the US). The other marketplaces come through CleanPull's marketplace data service." } } }, "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 } } } } } } } } } }