{ "openapi": "3.0.1", "info": { "title": "Etsy Listings Scraper", "description": "Scrape Etsy products by keyword, category, shop or listing URL: price, rating, reviews, ads and organic rank, bestseller badges. Reviews, shop details and emails as options. Export to JSON, CSV or Excel.", "version": "0.0", "x-build-id": "QF9E99EzgfIe8pI92" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nice_dev~etsy-listings-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nice_dev-etsy-listings-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/nice_dev~etsy-listings-scraper/runs": { "post": { "operationId": "runs-sync-nice_dev-etsy-listings-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/nice_dev~etsy-listings-scraper/run-sync": { "post": { "operationId": "run-sync-nice_dev-etsy-listings-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": { "startUrls": { "title": "Start URLs", "maxItems": 1000, "type": "array", "description": "Etsy URLs to read: search results (`https://www.etsy.com/search?q=ceramic+mug`, all filters set on the site are kept), category pages (`/c/...`), shop pages (`/shop/`: all the active listings of the shop) or single listings (`/listing/`). Paste the URLs one by one: importing a file of links is not supported. Pagination is automatic. They add up with the keywords, shop names and listing IDs below: everything is read in one run, each listing is saved once, and the caps, the filters of the Filters section and monitoring apply to all of it. Max 1 000 URLs.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "query": { "title": "Search keyword", "maxLength": 200, "type": "string", "description": "Free-text search, exactly as typed in Etsy's search box (e.g. `ceramic mug`). Leave empty to give only URLs, shops or listings." }, "searchQueries": { "title": "More search keywords", "maxItems": 100, "uniqueItems": true, "type": "array", "description": "Several keywords in one run: one search per keyword. Added to **Search keyword**; listings found by several searches are saved once.", "default": [], "items": { "type": "string" } }, "shopNames": { "title": "Shop names", "maxItems": 500, "uniqueItems": true, "type": "array", "description": "Etsy shop names (e.g. `KJPottery`) or shop URLs (`https://www.etsy.com/shop/KJPottery`): all the active listings of each shop, up to about 10 000. Use **Max listings per search** to cap each shop.", "default": [], "items": { "type": "string" } }, "listingUrls": { "title": "Listing URLs or IDs", "maxItems": 10000, "uniqueItems": true, "type": "array", "description": "Single listings by ID (`1234567890`) or URL (`https://www.etsy.com/listing/1234567890/...`). No search page is read: each listing gives its title, price, shop and photo, plus the extras you tick below.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max listings", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Maximum number of listings to save for the whole run (after deduplication and filters). 0 = no limit.", "default": 100 }, "maxItemsPerQuery": { "title": "Max listings per search", "minimum": 0, "maximum": 100000, "type": "integer", "description": "Cap for EACH search (keyword, search URL or shop), so that the first search cannot use up the whole **Max listings** budget. 0 = no per-search cap.", "default": 0 }, "sortBy": { "title": "Sort by", "enum": [ "most_relevant", "price_asc", "price_desc", "date_desc", "highest_reviews" ], "type": "string", "description": "Order of Etsy's results. Top customer reviews is Etsy's own sort by reviews. Etsy shows at most 20 pages of results, whatever the order. When Max listings asks for more than about 1,200, the search is read in price ranges: the order holds inside each range, not between them. With Most recent and Only new listings, only the first 20 pages are read. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": "most_relevant" }, "minPrice": { "title": "Min price", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Lowest price, in the currency Etsy shows for the search. Empty = no minimum. Keyword searches only: shops, listings and pasted URLs are read without it." }, "maxPrice": { "title": "Max price", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Highest price, in the currency Etsy shows for the search. Empty = no maximum. Keyword searches only: shops, listings and pasted URLs are read without it." }, "freeShippingOnly": { "title": "Free shipping only", "type": "boolean", "description": "Only listings with free shipping. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": false }, "onSaleOnly": { "title": "On sale only", "type": "boolean", "description": "Only discounted listings. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": false }, "customizableOnly": { "title": "Customizable only", "type": "boolean", "description": "Only listings the buyer can personalize. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": false }, "listingType": { "title": "Physical or digital", "enum": [ "physical", "digital", "all" ], "type": "string", "description": "Physical items only (Etsy's own default for most searches), instant digital downloads only, or both. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": "physical" }, "giftWrapOnly": { "title": "Gift wrapping only", "type": "boolean", "description": "Only listings the seller can gift-wrap. Keyword searches only: shops, listings and pasted URLs are read without it.", "default": false }, "readyToShipWithin": { "title": "Ready to ship in", "enum": [ "any", "1", "3" ], "type": "string", "description": "Etsy's Ready to ship filter: only listings whose shop ships within 1 or 3 days of the order. Sent with each keyword search, and added to a pasted search or category URL that has no such filter of its own. Not applied to shops or to listings given by ID or URL, which Etsy cannot filter that way.", "default": "any" }, "shipTo": { "title": "Ships to (country code)", "pattern": "^([A-Za-z]{2})?$", "maxLength": 2, "type": "string", "description": "Only listings that ship to this country, as a 2-letter code (`US`, `GB`, `DE`…). Empty = Etsy's default. Keyword searches only: shops, listings and pasted URLs are read without it." }, "location": { "title": "Shop country (code)", "pattern": "^([A-Za-z]{2})?$", "maxLength": 2, "type": "string", "description": "Only shops located in this country, as a 2-letter code (`US`, `GB`, `FR`…). Empty = anywhere. Keyword searches only: shops, listings and pasted URLs are read without it." }, "currency": { "title": "Currency", "enum": [ "USD", "EUR", "GBP", "CAD", "AUD", "NZD", "JPY", "CHF", "SEK", "DKK", "NOK", "PLN", "INR", "MXN", "BRL", "HKD", "SGD", "ILS" ], "type": "string", "description": "Currency of the prices (and of **Min price** / **Max price**). Default: US dollars. A listing given by ID or URL shows its price in the seller's own currency.", "default": "USD" }, "country": { "title": "Buyer country (code)", "pattern": "^([A-Za-z]{2})?$", "maxLength": 2, "type": "string", "description": "Country Etsy shops for, as a 2-letter code (`US`, `GB`, `DE`…): it changes the results, availability and shipping offers, like a visitor of that country. Empty = the proxy's country." }, "includeDetails": { "title": "Full listing details", "type": "boolean", "description": "Description, the tags (up to 13), materials, favorites, stock quantity, category path, creation date, all photos, made-to-order / digital / customizable flags, Etsy's item summary, the code of the country it ships from.", "default": false }, "includeDemandSignals": { "title": "Listing page: demand signals, variations, shipping", "type": "boolean", "description": "Opens one more page per listing (the listing page itself, slower). Gives the demand signals (\"In 20+ carts\", \"N people bought this in the last 24 hours\", \"Only N left\"), the variations (colors, sizes, with the price of each option when shown), the lowest and highest price, the shipping cost, region and delivery estimate, whether returns are accepted and for how many days, the rating and number of reviews of the listing itself, the video and the first name the shop shows. Charged for each listing page read, even when the page shows no demand signal.", "default": false }, "includeReviews": { "title": "Reviews", "type": "boolean", "description": "Buyer reviews of each listing: rating, text, date, reviewer, photos, seller reply.", "default": false }, "maxReviewsPerListing": { "title": "Max reviews per listing", "minimum": 0, "maximum": 500, "type": "integer", "description": "Cap on the reviews returned for each listing when **Reviews** is ticked (500 at most: Etsy gives a shop's reviews, not a listing's, and the Actor reads the latest 500 reviews of the shop). 0 = as many as it finds, up to 500.", "default": 20 }, "includeShopDetails": { "title": "Shop details", "type": "boolean", "description": "For each listing's shop: total sales, shop rating and review count, location, opening year, Star Seller, number of active listings, social links. One shop page per shop, reused for all its listings.", "default": false }, "includeShopEmail": { "title": "Shop contact e-mail", "type": "boolean", "description": "Public contact e-mail of the shop, looked up on the shop's own website and social profiles linked from Etsy. Needs **Shop details** ticked too. Charged only when an e-mail is found.", "default": false }, "postedAfter": { "title": "Listed after", "type": "string", "description": "Only listings created (or last renewed) on or after this date — Etsy's listing date: `2026-09-01`, or a period before now such as `7 days`, `2 weeks`, `1 month` (API: `24 hours` and full ISO date-times work too). Etsy cards carry no date: the Actor reads each listing's data to apply it." }, "postedBefore": { "title": "Listed before", "type": "string", "description": "Only listings created on or before this date (the whole day is included), or older than a period such as `30 days`." }, "excludeKeywords": { "title": "Exclude keywords", "maxItems": 50, "uniqueItems": true, "type": "array", "description": "Drop the listings whose title contains one of these words (case and accents ignored).", "default": [], "items": { "type": "string" } }, "minRating": { "title": "Min rating", "minimum": 0, "maximum": 5, "type": "number", "description": "Drop listings whose shop is rated below this (1-5; 0 = no filter): the shop rating the card shows, the same on all the listings of a shop. Listings without it are dropped too. Shop pages and listings given by ID or URL show no rating: their listings are kept. Empty or 0 = keep all." }, "minReviews": { "title": "Min review count", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Drop listings whose shop has fewer reviews than this: the shop review count the card shows, rounded by Etsy above 999 on a search page (1.7k = 1,700). Shop pages and listings given by ID or URL show no review count: their listings are kept. Empty = keep all." }, "bestsellersOnly": { "title": "Bestsellers only", "type": "boolean", "description": "Keep only listings with Etsy's Bestseller badge. Shop pages show no such badge: their listings are kept, unless an option reads the listing's own data (Full listing details, reviews, shop details, dates, minimum favorites…): Etsy's flag is then known and applied. A listing given by ID or URL that Etsy gives no flag for is kept too.", "default": false }, "starSellerOnly": { "title": "Star Sellers only", "type": "boolean", "description": "Only listings of Star Seller shops (Etsy's own filter for keywords, applied by the Actor to the other sources). Not applied to listings given by ID or URL (their data does not say).", "default": false }, "etsysPickOnly": { "title": "Etsy's Picks only", "type": "boolean", "description": "Keep only Etsy's Picks: asked of Etsy for keyword searches and pasted search or category URLs (its ads are still checked on their badge), read on the badge for shop pages. Not applied to listings given by ID or URL (their data does not say).", "default": false }, "minFavorites": { "title": "Min favorites", "minimum": 0, "maximum": 10000000, "type": "integer", "description": "Drop listings favorited by fewer people than this (reads the listing data: a listing it drops is charged the filter fee, a listing it keeps costs nothing more). Empty = keep all." }, "excludeAds": { "title": "Exclude ads", "type": "boolean", "description": "Drop the sponsored (Ad) listings of the search pages and keep the organic ones only.", "default": false }, "onlyNew": { "title": "Only new listings", "type": "boolean", "description": "Skip the listings that a previous run (same **Memory key**) already delivered: they are not saved and not charged, and their page is not even opened, except a listing given by ID or URL: its data is read at each run, then the listing is skipped, free of charge. First run = everything is new.", "default": false }, "stateKey": { "title": "Memory key", "pattern": "^[a-zA-Z0-9_-]{1,64}$", "maxLength": 64, "type": "string", "description": "Name of the memory used by **Only new listings**. Give each schedule / task its own key (e.g. `mugs-us`) so that they do not share their memory. Letters, digits, `-` and `_`.", "default": "default" }, "resetState": { "title": "Reset the memory", "type": "boolean", "description": "Forget everything remembered under this **Memory key** before the run: this run returns (and charges) every listing again. Untick it afterwards.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Apify Proxy or your own proxies. Keep the default: it is included in the price. The residential Apify proxy is not available in this Actor.", "default": { "useApifyProxy": true } }, "maxConcurrency": { "title": "Max concurrency", "minimum": 1, "maximum": 50, "type": "integer", "description": "Maximum number of requests processed in parallel.", "default": 8 }, "maxRequestsPerMinute": { "title": "Max requests per minute", "minimum": 10, "maximum": 2000, "type": "integer", "description": "Most requests to Etsy in any 60 seconds: search pages, listing pages, reviews and shop pages. A budget, not an even pace: up to this many can leave at once when the minute starts (spread them with the minimum delay below). Lower it if Etsy answers HTTP 429 / 403 in the log.", "default": 120 }, "minRequestIntervalMs": { "title": "Min delay between requests", "minimum": 0, "maximum": 60000, "type": "integer", "description": "Smallest gap between two requests, in milliseconds. Unlike the per-minute rate, this spreads the requests evenly instead of letting them go out in a burst. 0 = no gap.", "default": 0 }, "maxRequestRetries": { "title": "Max request retries", "minimum": 0, "maximum": 20, "type": "integer", "description": "Retries per request before it is marked as failed. Behind a proxy, a request the site turns away is also retried on a new proxy session up to 10 times without using up these retries.", "default": 5 }, "debugLog": { "title": "Debug log", "type": "boolean", "description": "Include debug messages in the run log.", "default": false } } }, "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 } } } } } } } } } }