Etsy API

Endpoints

Quick start

Coverage & limits

• Independent worker on port 3032, ETSY_API_KEY in x-api-key. No login, persistent cookies, proxy, storage, media download, Etsy developer key or product dependencies.
• Eight concurrent operations of which at most two browser device checks run at once (reads that waited for one reuse the session it cleared), 45-second total deadline, at most ten Etsy reads per operation (the requested page, the device-check re-read, up to two canonical redirect hops, the page-one primer that sorted or deep search pages use, one transient retry, and through a proxy up to two fresh exits). Challenges answered by Etsy itself, rate limits and 4xx answers are never retried.
• Documents and Etsy's own script-data modules (lazy search cards, similar listings, listing reviews) are read over plain HTTPS with a session a browser cleared earlier: at most three sessions in process memory (three cookie pairs and a CSRF nonce each, never content), 30 minutes or 300 reads each. When no session is usable, or Etsy refuses one, the read drives a fresh headed Patchright Chromium: only Etsy documents and the challenge vendor (captcha-delivery.com) may leave the process, subresources and third parties are refused, and the final document is taken from the network before rendering. The device check must clear within 15 seconds; a visible puzzle fails as upstream_challenged. ETSY_PROXY_URL (with an optional per-read session username template) routes the whole browser through a residential proxy; Linux containers enable Chromium's software WebGL for the check and require Xvfb; readiness checks the browser binary and display.
• 3 MiB decoded HTML per operation, 400,000 parsed nodes, depth 128; 36 listing cards, 24 similar listings, 8 listing reviews and 20 review tags per page, 14 reviews, 48 organic IDs and 20 suggestions per page; pages 1-250.
• Prices are pinned with Etsy's locale_override query parameter (currency|en-US|US); no preference cookie is stored. Search pages carry structured data for their first organic products and the ordered IDs of the rest (organic_results_partially_embedded). Sorted or deep search pages are read after the query's first page in the same browser session.
• Shop and listing identities are verified against the request; mismatches fail unsupported_page. Same-origin redirects are followed only to the shop's canonical casing or the listing's slugged path.
• The listing reviews module needs the shop ID next to the listing ID: the pair is read from the listing page once and remembered in process memory (identifiers only, at most 5,000 pairs, 24 hours, oldest evicted first); a miss reads the listing page again.