Skip to content

Structured Etsy data: send urls. Cursor-paginated, 1 credit per successful call.

GET · POST1 credit / successful callCursor-paginated
GEThttps://api.scrapier.io/api/v2/etsy-similar-products/Open in Playground

Call GET /api/v2/etsy-similar-products/ with urls. The results are in data.products; send data.next_cursor back as cursor to get the next page. 6 optional parameters refine the call (see Parameters).

Terminal window
curl -G "https://api.scrapier.io/api/v2/etsy-similar-products/" \
-H "X-API-Key: YOUR_API_KEY" \
--data-urlencode "urls=1215970085" \
--max-time 210
NameTypeRequiredDefaultDescription
X-API-Key headerstringyes—Your API key from the dashboard.
urlsstringyese.g. 1215970085Etsy listing URL or numeric listing id. Required on the first call (list -> first only). 20 products per page.
cursorstringno—Pagination cursor returned in the previous response's next_cursor. Pass it back unchanged to fetch the next page. When next_cursor is null, you have reached the last page.
countrystringnoUSShip-to country.
locked in cursor
currencystringnoUSDPrice currency.
locked in cursor
localestringnoen-USCopy language.
locked in cursor
include_unavailablebooleannofalse
locked in cursor
expand_similarbooleannotrueSimilar-of-similar expansion past ~40.
locked in cursor
Advanced
NameTypeDefaultDescription
use_proxybooleantrueRoute the request through Scrapier's residential proxy pool. Default: true. Leave as is unless support tells you otherwise.
raw_databooleanfalseWhen true, the response carries the full raw upstream payload(s) the scraper received (GraphQL / JSON API bodies, HTML, embedded JSON-LD -- exactly as the platform returned them) under raw_responses, in place of the formatted items. When false (default) you get the formatted output. Pagination (cursor / next_cursor) works the same in both modes.
{
"success": true,
"data": {
"urls": "1215970085",
"listing_id": "1215970085",
"source_listing": {
"id": "1215970085",
"url": "https://www.etsy.com/listing/1215970085/custom-air-freshener-picture-air",
"title": "Custom Air Freshener, Picture Air Freshener, ...",
"seller": "TheFreshener",
"seller_id": "35332887"
},
"page": 1,
"page_size": 20,
"products": [
{
"input_url": "1215970085",
"source_listing_id": "1215970085",
"position": 1,
"depth": 1,
"similar_to_listing_id": "1215970085",
"id": "4557154966",
"url": "https://www.etsy.com/listing/4557154966/custom-air-freshener-picture-air",
"title": "Custom Air Freshener, Picture Air Freshener, Cute Car Accessories, Photo Freshener, Car Freshies, Car Decor",
"description": "Custom Face Cut Car Air Freshener. Versatile Scent Selection...",
"seller": "DidiDecous",
"brand": null,
"price": {
"current": 11.98,
"original": 23.96,
"currency": "USD"
},
"rating": {
"average": 4.66,
"count": 47
},
"image_urls": [
"https://i.etsystatic.com/61480419/r/il/17ef7d/8372827043/il_fullxfull.8372827043_mdpo.jpg"
],
"availability": "in_stock",
"reviews_count": 47,
"ext": {
"seller_id": "61480419",
"available_quantity": 2989,
"etsy": {
"is_handmade": true,
"is_bestseller": false,
"is_made_to_order": true,
"when_made": "made_to_order",
"discount_percent": 50,
"free_shipping": false,
"ships_from_country": "US",
"favorites": 1,
"tags": [
"car freshener funny",
"cute car air fresh"
],
"materials": [
"Paper"
],
"category": {
"id": 1895,
"name": "Car Accessories",
"path": "electronics_and_accessories.car_parts_and_accessories.car_accessories"
},
"shop": {
"shop_id": "61480419",
"name": "DidiDecous",
"url": "https://www.etsy.com/shop/DidiDecous",
"rating_average": 4.66,
"rating_count": 47,
"sold_count": 356,
"active_listing_count": 71,
"country_code": "US",
"is_open": true
},
"language": "en-US",
"created_at": "2026-08-17T09:50:20Z",
"updated_at": "2026-09-01T01:22:41Z"
}
},
"source_listing": {
"id": "1215970085",
"url": "https://www.etsy.com/listing/1215970085/custom-air-freshener-picture-air",
"title": "Custom Air Freshener, Picture Air Freshener, ...",
"seller": "TheFreshener",
"seller_id": "35332887"
},
"scraped_at": "2026-09-24T13:17:36.454Z"
}
],
"next_cursor": "eyJpIjoiMTIxNTk3MDA4NSIsImxrIjp7ImNvdW50cnkiOiJVUyIsImN1cnJlbmN5IjoiVVNEIn0sIm8iOjIwLCJwIjoyfQ"
}
}

Sample from the live catalog; arrays trimmed to 3 items. Results are in data.products.

FieldTypeExampleDescription
urlsstring1215970085—
listing_idstring1215970085—
source_listingobject{…}—
pageinteger1—
page_sizeinteger20—
productsarray[1 item]The results.
next_cursorstringeyJpIjoiMTIxNTk3MDA4NSIsImxrIjp7ImNvdW50cnkiO…Pass back as cursor for the next page. null on the last page.
products[].input_urlstring1215970085—
products[].source_listing_idstring1215970085—
products[].positioninteger1—
products[].depthinteger1—
products[].similar_to_listing_idstring1215970085—
products[].idstring4557154966—
products[].urlstringhttps://www.etsy.com/listing/4557154966/custo…—
products[].titlestringCustom Air Freshener, Picture Air Freshener, …—
products[].descriptionstringCustom Face Cut Car Air Freshener. Versatile …—
products[].sellerstringDidiDecous—
products[].brandnullnull—
products[].priceobject{…}—
products[].ratingobject{…}—
products[].image_urlsarray[1 item]—
products[].availabilitystringin_stock—
products[].reviews_countinteger47—
products[].extobject{…}—
products[].source_listingobject{…}—
products[].scraped_atstring2026-09-24T13:17:36.454Z—

Pass data.next_cursor back as cursor until it is null. Required inputs are ignored once a cursor is sent. Each page is one billed call. More in Pagination.

const url = "https://api.scrapier.io/api/v2/etsy-similar-products/";
let params = { urls: "1215970085" };
const items = [];
for (let page = 0; page < 10; page++) { // each page is one billed call
const res = await fetch(`${url}?${new URLSearchParams(params)}`, {
headers: { "X-API-Key": "YOUR_API_KEY" },
signal: AbortSignal.timeout(210_000),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error ?? body.detail ?? `HTTP ${res.status}`);
const data = body.data;
items.push(...(data.products ?? []));
if (!data.next_cursor) break; // null = last page
params = { cursor: data.next_cursor };
}

Failed calls are free. Branch on the HTTP status and read the message from error (or detail). Full details in Errors.

StatusMeaningRetry?Charged?
400Bad or missing input.No — fix the paramsNo
401 / 403Missing, invalid or revoked API key.No — fix the keyNo
402Out of credits (body has balance).No — top upNo
404Unknown endpoint slug.No — check the slugNo
429 / 503Busy or throttled.Yes — after Retry-AfterNo
5xxTarget site or upstream failure, or timeout.Yes — with backoffNo
  • Locked into the cursor: country, currency, locale, include_unavailable, expand_similar. Set them on the first call; later pages reuse them.