Etsy Listings Scraper

Discover Etsy listings from keyword searches for product research, assortment monitoring, and competitor discovery. This Actor returns a clean dataset of listing IDs, canonical Etsy URLs, titles, indexed snippets, and any indexed shop or rating metadata.

It is a listing-discovery Actor. It does not open Etsy listing pages and does not claim live prices, carts, ads, inventory, shipping, seller sales, full descriptions, or review details. That narrow contract is intentional: the data is sourced from public search-index results, so every returned row carries dataSource: "public-search-index" and its originating query.

When to use it

Use this Actor when you need a quick, structured list of Etsy products for a keyword, such as handmade necklace, personalized leather journal, or printable wedding invitation. It is useful for building a candidate set for market research, monitoring which listings are publicly discoverable, and sending stable Etsy listing URLs to another workflow.

Do not use it when you need current listing-page facts such as a product price, stock, variations, delivery terms, photos, shop analytics, customer reviews, promoted placement, or cart activity. Those values are not guaranteed by a public search index and are deliberately not fabricated here.

Output

Each dataset item is a validated listing-discovery record:

Field	Meaning
listingId	Etsy listing identifier parsed from the canonical URL.
listingUrl	Canonical Etsy listing URL.
title	Title visible in the public search result.
description	Indexed result snippet in detailed mode, otherwise null.
rating, reviewCount, shopName	Metadata only when the search index exposes it; otherwise null.
sourceQuery, sourceSearchUrl	Query and index request that found the listing.
resultPosition	One-based position within the parsed index page.
scrapedAt, dataSource, parseWarnings	Provenance and safe availability diagnostics.

The default key-value store also contains OUTPUT and RUN_SUMMARY. OUTPUT is a compact stable machine contract. RUN_SUMMARY explains source coverage, duplicate handling, row validation, warnings, and charged events.

Pricing

• Actor start: $0.00005 per GB of configured memory
• Etsy listing returned: $0.003 for each validated record successfully written to the dataset

Platform compute and residential proxy usage are additional under Pay per event + usage. maxResults is both the dataset and event-cost cap. For example, maxResults: 50 caps primary listing-event charges at $0.15, plus the small start charge and platform usage.

No event is charged for an invalid, duplicate, or failed dataset row.

Input

searchQueries accepts up to 20 keyword phrases. If omitted, the safe default query is handmade necklace, which lets quality checks execute a useful, bounded run. An explicitly empty query list is rejected with an actionable INVALID_INPUT outcome.

maxResults is the global cap from 1 to 200. maxPagesPerQuery controls how many public search-index pages are requested per query, from 1 to 10. responseFormat: "concise" returns stable listing-discovery fields with a null description; use "detailed" only when you want the optional indexed snippet. Set deduplicateAcrossQueries to false if you want to retain the same listing under multiple search queries.

Apify Console input

{
  "searchQueries": ["handmade necklace", "personalized leather journal"],
  "maxResults": 50,
  "maxPagesPerQuery": 2,
  "responseFormat": "concise",
  "deduplicateAcrossQueries": true
}

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('khadinakbar/etsy-listings-scraper').call({
  searchQueries: ['handmade necklace'],
  maxResults: 20,
  maxPagesPerQuery: 2,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);

Python

from apify_client import ApifyClient
import os

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('khadinakbar/etsy-listings-scraper').call(run_input={
    'searchQueries': ['personalized leather journal'],
    'maxResults': 20,
    'responseFormat': 'detailed',
})
for item in client.dataset(run['defaultDatasetId']).iterate_items():
    print(item['listingUrl'], item['title'])

Outcomes and operational behavior

The Actor always writes OUTPUT and RUN_SUMMARY before its terminal state. COMPLETE means every requested source completed with useful persisted rows. PARTIAL preserves useful rows but reports exhausted sources, row validation failures, or a charge cap. VALID_EMPTY means the public search index processed valid input and exposed no Etsy listing records. INVALID_INPUT provides a correction example. UPSTREAM_FAILED is used honestly when every required public-index source fails before any useful row can be written.

Rows are normalized, validated, written, and charged in one SDK call. The actor retries a transient source failure up to three times with the same residential session identifier. It never writes diagnostic or placeholder rows into the dataset.

Tips

• Start with one precise phrase. Add query variations only after checking the first dataset.
• Treat rating, reviewCount, shopName, and description as optional fields. A null value means the search index did not expose that field.
• Use the canonical listingUrl as a join key for your own approved downstream workflows.
• Use scheduled runs for visibility tracking, then compare datasets by listingId; search-index ordering and availability may change over time.

FAQ

Why is the price missing? This Actor intentionally does not claim direct listing-page data. Search-index snippets are not a reliable product-price contract.

Can I pass Etsy URLs? No. This actor accepts keyword discovery only, which keeps the input small and the output provenance clear.

Why did the Actor return VALID_EMPTY? The search-index route worked, but it did not expose qualifying Etsy listing links for the supplied query and requested pages.

Why did the Actor return UPSTREAM_FAILED? The public search-index route failed before any useful listing row could be persisted. Inspect RUN_SUMMARY.warnings and retry later with a smaller query set.

Responsible use

Use this Actor only for lawful, authorized purposes and in accordance with the terms that apply to your use of Etsy and any downstream data source. Do not use it to collect private information, bypass access controls, or make decisions that materially affect people without appropriate review.