{ "openapi": "3.0.1", "info": { "title": "Etsy Scraper — Listings, Prices, Shops & Badges", "description": "Scrape Etsy search results, shop pages and listings: title, price, sale price, shop, rating, review count, Bestseller and Star Seller badges, images and details. Any keyword, shop or listing URL.", "version": "0.1", "x-build-id": "WbeNFsYdJq07n3Dhg" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/tortuga~etsy-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-tortuga-etsy-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/tortuga~etsy-scraper/runs": { "post": { "operationId": "runs-sync-tortuga-etsy-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/tortuga~etsy-scraper/run-sync": { "post": { "operationId": "run-sync-tortuga-etsy-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": { "searchTerms": { "title": "Search terms", "type": "array", "description": "Keywords to search on Etsy, one per line (e.g. \"ceramic mug\", \"personalized necklace\"). Each term is searched separately and paginated automatically: one request returns a result page with 48 listings plus up to 24 sponsored listings.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Etsy URLs to scrape instead of (or in addition to) search terms: search pages (https://www.etsy.com/search?q=ceramic+mug), category pages (https://www.etsy.com/c/home-and-living/…/drinkware/mugs), market pages (https://www.etsy.com/market/ceramic_mug, run as the search \"ceramic mug\"), shop pages (https://www.etsy.com/shop/CeramicArtisanMan, all items of the shop) or listing pages (https://www.etsy.com/listing/4296141840/…, returned with full details). Filters in a search URL are kept.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "maxItems": { "title": "Max items", "minimum": 1, "type": "integer", "description": "Stop after this many listings in total (across all search terms and URLs). Keeps cost predictable.", "default": 100 }, "maxPagesPerSearch": { "title": "Max pages per search", "minimum": 1, "maximum": 250, "type": "integer", "description": "How many result pages to open per search term or URL (48 listings each plus sponsored ones, one proxy request per page; shop pages list 36 items). Etsy itself serves at most 20 pages of a relevance-sorted search and 250 pages of a sorted one.", "default": 5 }, "sortBy": { "title": "Sort by", "enum": [ "most_relevant", "price_asc", "price_desc", "date_desc", "highest_reviews" ], "type": "string", "description": "Result order for search terms and search URLs, as on Etsy's own \"Sort by\" menu. Shop pages support the price orders and newest; category pages are read in Etsy's order.", "default": "most_relevant" }, "minPrice": { "title": "Min price (USD)", "minimum": 0, "type": "integer", "description": "Only listings at or above this price. Sent to Etsy as its own price filter for searches; listings outside the range on any page are dropped before saving and never charged." }, "maxPrice": { "title": "Max price (USD)", "minimum": 0, "type": "integer", "description": "Only listings at or below this price (Etsy's own price filter for searches; applied to every page before saving)." }, "includeDetails": { "title": "Include listing details", "type": "boolean", "description": "Also open every listing page to get the description, materials, variations with their prices, stock, favorites count, shipping and returns, estimated delivery, all images, category path, listed-on date, exact item rating and review count, review highlights and the shop profile (location, sales, rating, review count, years on Etsy, Star Seller). One extra proxy request and one extra `detail` charge per listing (see pricing).", "default": false }, "onlyNewOrChanged": { "title": "Only new or changed items", "type": "boolean", "description": "Remember what earlier runs of this search returned and output only new items or items whose price/status changed. Use with a Schedule; unchanged items are not charged. With this on, Max items is the number of listings checked each run (the watched window, e.g. the newest 40), so a run never digs deeper than the first one. Price, original price (sales) and the stock hint (\"Only 1 left\") are compared; price moves within 2% count as unchanged (non-US shops' prices are converted to USD and move with the exchange rate). Sponsored listings are skipped while monitoring: Etsy rotates them on every visit.", "default": false }, "monitoringKey": { "title": "Monitoring key", "type": "string", "description": "Name for this watch, so several schedules on the same search stay separate; defaults to a key derived from the search input." }, "country": { "title": "Country", "enum": [ "US" ], "type": "string", "description": "Etsy storefront to scrape. Prices come in that country's currency and the proxy is pinned to it. Only the United States (USD, English) is supported so far: other exit countries did not get through the proxy.", "default": "US" }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Etsy answers datacenter and residential proxies with an error, so the default is Apify's Unblocker proxy (group UNBLOCKER), pinned to the selected country. It is billed to your Apify account per successful request: 10 Unblocker units, about $0.0015 on the free plan and less on paid plans. One request returns a result page with about 60 listings (36 on shop pages), or one listing page. Requests take 10-60 seconds each.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "UNBLOCKER" ], "apifyProxyCountry": "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 } } } } } } } } } }