{ "openapi": "3.0.1", "info": { "title": "eBay Scraper - Products, Sellers, Prices & Monitoring", "description": "Scrape eBay by keyword, category, seller or pasted link across 16 country storefronts. Returns id, title, condition, price, buying format, delivery, returns, seller feedback and more, with optional item specifics and full descriptions. Incremental mode tracks changes.", "version": "1.0", "x-build-id": "jeZ1QSgHtlqY0WbCF" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/abotapi~ebay-com-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-abotapi-ebay-com-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/abotapi~ebay-com-scraper/runs": { "post": { "operationId": "runs-sync-abotapi-ebay-com-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/abotapi~ebay-com-scraper/run-sync": { "post": { "operationId": "run-sync-abotapi-ebay-com-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "url" ], "type": "string", "description": "Choose 'search' to search a marketplace by keyword, seller, category and filters, or 'url' to scrape pasted links.", "default": "search" }, "queries": { "title": "Search keywords", "type": "array", "description": "Only used when mode = search, ignored in url mode. One or more keywords, for example 'laptop', 'pokemon card' or a part number. Leave empty to browse a category or a seller alone.", "items": { "type": "string" } }, "sellerUsernames": { "title": "Sellers", "type": "array", "description": "Only used when mode = search, ignored in url mode. One or more seller usernames, for example 'examplestore'. Each seller's own listing page is walked forward. Combine with keywords, or use on its own to pull a whole store.", "items": { "type": "string" } }, "marketplace": { "title": "Marketplace", "enum": [ "com", "co.uk", "de", "com.au", "ca", "fr", "it", "es", "ie", "at", "ch", "nl", "pl", "com.hk", "com.sg", "com.my" ], "type": "string", "description": "Only used when mode = search, ignored in url mode where the marketplace is taken from each pasted link's own address. Every option here was checked live and returns real results. Prices come back in that marketplace's own currency.", "default": "com" }, "categoryId": { "title": "Category id", "type": "string", "description": "Optional. Keep only listings in this marketplace category, given as the NUMERIC id that appears in the marketplace's own category links (for example 177 for PC laptops). A category name is not accepted: it is ignored with a warning in the run log. Combine with a keyword, or use on its own to browse a whole category." }, "condition": { "title": "Condition", "uniqueItems": true, "type": "array", "description": "Optional. Keep only listings in these conditions. Selecting several returns listings in any of them. Applied by the marketplace itself, so it narrows the result count at the source.", "items": { "type": "string", "enum": [ "new", "open_box", "certified_refurbished", "excellent_refurbished", "very_good_refurbished", "good_refurbished", "seller_refurbished", "used", "for_parts" ], "enumTitles": [ "New", "Open box", "Certified refurbished", "Excellent refurbished", "Very good refurbished", "Good refurbished", "Seller refurbished", "Used", "For parts or not working" ] } }, "buyingFormat": { "title": "Buying format", "enum": [ "any", "buy_it_now", "auction", "best_offer" ], "type": "string", "description": "Optional. Keep only listings sold in this format. Applied by the marketplace itself.", "default": "any" }, "minPrice": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Optional. Keep only listings priced at or above this amount, in the selected marketplace's own currency. Applied by the marketplace itself." }, "maxPrice": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Optional. Keep only listings priced at or below this amount, in the selected marketplace's own currency. Applied by the marketplace itself." }, "freeShippingOnly": { "title": "Free delivery only", "type": "boolean", "description": "Optional. Keep only listings the marketplace flags as free delivery. Applied by the marketplace itself.", "default": false }, "freeReturnsOnly": { "title": "Free returns only", "type": "boolean", "description": "Optional. Keep only listings that offer free returns. Applied by the marketplace itself.", "default": false }, "returnsAcceptedOnly": { "title": "Returns accepted only", "type": "boolean", "description": "Optional. Keep only listings that accept returns at all, whether or not the buyer pays for them. Applied by the marketplace itself.", "default": false }, "itemLocation": { "title": "Item location", "enum": [ "default", "marketplace_country", "continent", "worldwide" ], "type": "string", "description": "Optional. Keep only listings held in this region, as the marketplace defines it relative to the storefront you selected. Applied by the marketplace itself.", "default": "default" }, "sortBy": { "title": "Sort by", "enum": [ "best_match", "ending_soonest", "newly_listed", "price_shipping_lowest", "price_shipping_highest", "distance_nearest" ], "type": "string", "description": "The order the marketplace returns results in. All five are the marketplace's own orderings, applied at the source. Promoted listings can still appear ahead of the requested order.", "default": "best_match" }, "sortOrder": { "title": "Sort order (alias of Sort by)", "enum": [ "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest", "distanceNearest" ], "type": "string", "description": "Same orderings under alternative names; used only when Sort by is left at its default." }, "keywords": { "title": "Keywords (alias of Search keywords)", "type": "array", "description": "Same as Search keywords; used only when Search keywords is empty.", "items": { "type": "string" } }, "ebaySite": { "title": "eBay site (alias of Marketplace)", "type": "string", "description": "Same as Marketplace, used only when Marketplace is empty. Accepts 'ebay.co.uk' or 'co.uk'." }, "subcategoryId": { "title": "Subcategory ID", "type": "string", "description": "Numeric category id that overrides Category ID when set." }, "itemCondition": { "title": "Item condition (any / new / used)", "enum": [ "any", "new", "used" ], "type": "string", "description": "Quick condition filter, used only when the Condition list is empty.", "default": "any" }, "conditionId": { "title": "Condition ID", "type": "integer", "description": "Marketplace condition id (1000 New, 3000 Used, 2000 Certified refurbished, 7000 For parts...). Overrides Item condition." }, "aspectFilter": { "title": "Item-specific filter", "type": "object", "description": "Item-specific facets as an object, for example {\"Brand\": \"Nike\"}. A list of values is OR-ed." }, "postalCode": { "title": "Postal code (for nearest-first sorting)", "type": "string", "description": "Origin for the 'Distance: nearest first' sort." }, "urls": { "title": "Marketplace links", "type": "array", "description": "Only used when mode = url, ignored in search mode. Mix freely: item pages such as /itm/123456789012 , result pages such as /sch/i.html?_nkw=laptop , seller listing pages such as /sch/examplestore/m.html , browse category pages such as /b/PC-Laptops-Netbooks/177 , and catalog product pages such as /p/7041718861 (scraped as that product's listings).", "default": [ "https://www.ebay.com/sch/i.html?_nkw=mechanical+keyboard", "https://www.ebay.co.uk/sch/i.html?_nkw=vinyl+record", "https://www.ebay.com/sch/i.html?_nkw=laptop&_pgn=2&_sop=15&LH_BIN=1&_ipg=240", "https://www.ebay.com/b/PC-Laptops-Netbooks/177/bn_317584", "https://www.ebay.com/sch/i.html?_ssn=ebay", "https://www.ebay.com/itm/286601719329", "https://www.ebay.co.uk/itm/286601719329", "https://www.ebay.com/p/7041718861" ], "items": { "type": "string" } }, "minSellerFeedbackPercent": { "title": "Minimum seller feedback percentage", "minimum": 0, "maximum": 100, "type": "integer", "description": "Optional. Keep only listings from sellers with at least this positive feedback percentage. Applied to the results in both modes. A seller too new to have a score yet is kept rather than dropped." }, "fetchDetails": { "title": "Read item pages", "type": "boolean", "description": "Read each listing's own item page for the full image gallery, the item specifics table, the category trail, brand, MPN, model, quantity available and sold, payment methods and the seller's full description. One extra request per listing, billed as one Item page event per listing returned. Pasted item links always read their item page, since a pasted link has no result card behind it. If the marketplace refuses some item pages, every affected listing is retried once before the run ends; a listing that still could not be read ships with its result-card fields, carries detailIncomplete: true, and is not billed the item page event.", "default": false }, "maxReviewsPerProduct": { "title": "Max seller feedback comments per listing", "minimum": 0, "maximum": 50, "type": "integer", "description": "How many of the seller's most recent public feedback comments to attach to each listing as `reviews` (reviewer, rating, date, text). Off by default (0). Only applies when item pages are read. Limited to 50, one feedback page, because the marketplace shows no more per page. The seller's feedback page is read once per seller per run, and every started block of 10 delivered comments adds one Item page event once per seller, on the first listing of that seller that is returned; later listings from the same seller carry the same comments at no extra charge.", "default": 0 }, "maxItems": { "title": "Max listings", "minimum": 0, "type": "integer", "description": "Maximum number of listings to return across the whole run. This is the run's cap. Use 0 for unlimited.", "default": 20 }, "maxPages": { "title": "Max result pages per keyword, seller or link", "minimum": 0, "type": "integer", "description": "Maximum number of result pages read per keyword, seller or link. 0 means no limit set by you, which is the default: the run then stops at Max listings, at the end of the results, when a page returns nothing new, or at a built-in ceiling of 100 pages per keyword, seller or link, whichever comes first.", "default": 0 }, "proxy": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy is recommended. Residential is the default and gives the most reliable results; free Apify plans continue on a backup connection.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }, "resumeFromRunId": { "title": "Resume from a previous run", "type": "string", "description": "Paste a previous run ID or dataset ID to continue a large pull without returning or charging for listings already collected there. Use this after an interrupted run. For recurring monitoring of the same search, use Incremental mode below instead." }, "incrementalMode": { "title": "Incremental changes for scheduled runs", "type": "boolean", "description": "Turn this on for daily or recurring monitoring. The first run returns every matching listing as NEW. Later runs normally return only NEW, UPDATED and REAPPEARED listings. A listing counts as UPDATED when any output field changes (price, bids, shipping, seller, title, condition, sold count and so on), and changedFields names them; scrapedAt, timeLeft, attributes, updatedAt, sourceUrl, pageNumber and searchQuery are excluded because they change on every fetch, and you can exclude more with Ignore fields. Turn on Emit unchanged or Emit expired only when you also want those rows returned (and billed). State is kept separately for each search, filter and lookup setup; use State key to name or deliberately share a monitoring campaign.", "default": false }, "stateKey": { "title": "State key (optional, incremental mode only)", "type": "string", "description": "Optional. Name this monitoring campaign to keep its state stable, or to deliberately share state across differently configured runs. Leave empty to let the actor derive a key automatically from the mode, marketplace, keywords, sellers, links and filters, so different searches never mix state with each other." }, "emitUnchanged": { "title": "Emit unchanged listings (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return listings that have not changed since the last run, marked UNCHANGED. This returns, and bills, extra rows you already have, so leave it off unless you want the full snapshot every run.", "default": false }, "emitExpired": { "title": "Emit expired listings (incremental mode only)", "type": "boolean", "description": "Off by default. Turn on to also return listings that were present in a previous run but are no longer found, marked EXPIRED. Only produced once a run has fully scanned the tracked search, so never when Max listings capped it, when Resume was used, or when a pasted link starts after page 1. This returns, and bills, extra synthetic rows, so leave it off unless you need expiry tracking.", "default": false }, "ignoreFieldsForChanges": { "title": "Ignore fields when detecting changes (incremental mode only)", "type": "array", "description": "Field names that must NOT count as a change when Incremental mode compares a listing with the last run, for example soldCount or imageUrl. A plain name is ignored at any depth; use a dotted path such as shippingDetails.cost for one nested field. The fields still appear in the output and are simply left out of the comparison and out of changedFields. Changing this list never causes a one-time wave of UPDATED rows. Built in, always ignored: scrapedAt, timeLeft, attributes, updatedAt, sourceUrl, pageNumber and searchQuery.", "items": { "type": "string" } }, "mcpConnectors": { "title": "Pipe results into your apps (optional)", "type": "array", "description": "Optionally send results into the apps you already use, via Model Context Protocol (MCP) connectors. Authorize one under Apify, Settings, API & Integrations, then select it here. Notion gets a rich page-per-item export; other connectors get a best-effort write or digest. Leave empty to skip; never changes the dataset output. Supported: Notion (https://mcp.notion.com/mcp), Linear (https://mcp.linear.app/sse), Airtable (https://mcp.airtable.com/mcp), Apify (https://mcp.apify.com)." }, "notionParentPageUrl": { "title": "Notion parent page (Notion connector only)", "type": "string", "description": "URL or id of the Notion page under which item pages are created. Required to enable the Notion export; ignored by other connectors." }, "maxNotifyListings": { "title": "Max items to export per connector", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Cap on items written to each connector per run. Does not affect the dataset.", "default": 50 } } }, "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 } } } } } } } } } }