Etsy Scraper + Listing Change Monitor

Use this Etsy scraper to search public US listings, inspect exact public listing details, collect a bounded shop catalog, or track verified listing changes. Every delivered row keeps a stable identity, and every run explains whether the requested scope was complete, capped, filtered, partial, blocked, failed, or positively empty.

Start with one keyword and 25 core listings. You receive analysis-ready Dataset rows plus a free coverage row that explains what Etsy exposed for that target.

🚀 Start in 60 seconds

1. Choose Search Etsy products.
2. Enter one buyer-style keyword.
3. Keep Core listing cards and the 25-listing default.
4. Run the Actor, open the Dataset, and check the free coverage row before increasing the limit.

{
  "workflow": "search_products",
  "queries": ["handmade silver ring"],
  "maxListings": 25,
  "detailLevel": "core",
  "marketCountry": "US",
  "currency": "USD",
  "maxBuyerChargeUsd": 5
}

🎯 Choose the right workflow

Workflow	Use it when	Required input	Current evidence
Search Etsy products	Keyword research, price comparison and placement analysis	queries	US keyword search returned listing IDs, titles, prices, currencies and images with COMPLETE coverage
Analyze Etsy shops	A public shop profile and its current catalog window	shops	Public shop catalog returned 25 listings plus one shop row and declared CAPPED coverage
Scrape exact listings	Known public listing IDs or URLs that need additional fields	listingTargets	Exact detail returned title, price, currency, shop, rating, review count, description, video and shipping
Track listing changes	Sequential comparison of the same search, shop or exact-listing scope	Matching target fields plus stateNamespace	Baseline, unchanged repeat, simultaneous changes and recovery behavior are mechanically verified

US keyword search, exact public listing detail and a bounded public shop-catalog window are the release-supported source groups. Other coverage stays inside the limitations listed below.

📦 What you get

Core listing rows

Core rows can include:

• stable listing ID and canonical public URL;
• title, current price, original price and currency;
• main image and observed query/page/rank placements;
• public shop name when Etsy includes it on the observed page;
• rating, review count, product type, badges and shipping signals when published;
• explicit sponsored, in-cart or recent-purchase values only when Etsy displays them.

Missing conditional fields stay null. The Actor does not estimate sales, demand, popularity, quality, sentiment or future performance.

Detailed listing and shop rows

Successful detailed rows can additionally include description, images, video, categories, tags, materials, personalization, variations, shipping, returns and processing information when Etsy publishes them. A successful detailed row uses detailed_listing_result instead of listing_result; the two listing events are never stacked for the same row.

Shop rows can include the public shop identity, URL, location, rating, review count, active-listing count, announcement, sections and logo when available. The same shop is charged at most once per run.

Coverage and monitoring rows

Coverage rows are free. They report targets, pages visited, raw and unique listing counts, duplicates merged, filters applied, detail success, field population and the exact stop reason.

Monitoring can return paid NEW or UPDATED rows and free NOT_OBSERVED notices. NOT_OBSERVED means only that an item was absent from the same bounded search or shop window; it never means deleted, sold, inactive or unavailable.

Representative synthetic listing row:

{
  "recordType": "listing",
  "stableId": "etsy:listing:synthetic-001",
  "listingId": "synthetic-001",
  "title": "Synthetic handmade silver ring",
  "priceAmount": 42,
  "currency": "USD",
  "imageCount": 1,
  "detailStatus": "CORE",
  "paid": true,
  "paidEvent": "listing_result",
  "sourceClass": "PUBLIC_FIRST_PARTY",
  "sourceName": "Etsy",
  "sourceUrl": null,
  "sourceContractVersion": "etsy-public-first-party-v2"
}

This is a synthetic schema example, not a live Etsy listing.

🎛️ Input guide

Targets and limits

The input schema has hard safety ceilings of 50 queries, 100 shops, 10,000 exact listing targets, 50,000 current-data rows and 250 pages per target. Those limits have passed the real local runtime and resource guards, but they are capacity controls—not live-source coverage promises.

The release canaries verified one US keyword target with maxListings: 25, one exact public listing with one detail and one shop row, and one public shop target with maxListings: 25 and one shop row. Larger live workloads are not yet supported as a Store promise. Reaching any page, listing, resource or charge ceiling returns CAPPED, never false completion.

categoryUrls accepts public Etsy category or market URLs, but pagination beyond the first verified page is not yet supported as a release promise.

Filters

Price range, product type, handmade, sale, free shipping, rating, review count, shop location and sort settings become part of the exact monitoring scope. Currency values are preserved as Etsy published them; no exchange-rate conversion is performed.

Cart, recent-purchase and sponsored fields are conditional. Sorting by those values uses only explicit numeric signals; missing values sort last and are never estimated.

Detail work

• core: use search or shop cards only.
• detailed: open up to maxDetailListings public listing pages.
• complete: perform the same listing detail work and add up to maxShopProfiles public shop profiles.

If detail work is unavailable, the valid core listing remains in the Dataset, its detailStatus becomes PARTIAL, coverage becomes PARTIAL, and no detailed-listing event is charged for that row.

Monitoring

The default first monitoring run creates a baseline without paid NEW rows. Choose emit_current_as_new only when the first current snapshot should be returned as paid NEW events.

Repeat runs must use the same stateNamespace and exactly the same targets, filters and limits. Runs for the same state scope must execute sequentially.

💰 Pricing

The complete charge is:

run charge = successful run or monitored targets + mutually exclusive core/detailed listing rows + shop rows + verified change rows

Event	Free	Bronze	Silver	Gold	Platinum	Diamond
Successful trustworthy run	$0.208	$0.208	$0.208	$0.208	$0.208	$0.208
Monitored target	$0.001	$0.0009	$0.0008	$0.0007	$0.0006	$0.0005
Core listing	$0.0016	$0.001336	$0.001064	$0.0008	$0.0008	$0.0008
Detailed listing	$0.011	$0.011	$0.011	$0.011	$0.011	$0.011
Shop profile	$0.003	$0.0028	$0.0026	$0.0024	$0.0022	$0.002
Public review	Reserved; not yet supported	Reserved; not yet supported	Reserved; not yet supported	Reserved; not yet supported	Reserved; not yet supported	Reserved; not yet supported
Verified change	$0.0016	$0.001336	$0.001064	$0.0008	$0.0008	$0.0008

Free-plan examples:

• 25 delivered core listings: $0.208 + 25 × $0.0016 = $0.248.
• One successful detailed listing plus one shop profile: $0.208 + $0.011 + $0.003 = $0.222.

Coverage rows, warnings, duplicate placements, UNCHANGED observations and NOT_OBSERVED notices are free. Blocked, failed and challenge-stopped runs do not accept the successful-run event. A successful detailed listing replaces the core listing event rather than adding another charge.

✅ Coverage you can trust

• COMPLETE: every requested page in the comparable exposed scope was exhausted.
• CAPPED: a declared limit stopped otherwise useful work while more may exist.
• PARTIAL: useful rows were delivered, but requested discovery or detail work did not finish.
• FILTERED: the public source was reached and buyer filters removed some rows.
• BLOCKED: a verified access condition prevented trustworthy completion.
• FAILED: the expected public data shape or reliable transport was not available.
• EMPTY_CONFIRMED: the expected current public shape positively showed no matching rows.

Blocked, failed or incomplete results never become empty success and never advance monitoring state. The Actor does not emit ENDED because search or shop disappearance is not proof of removal.

🔌 API and automation

Use the same input JSON with the Apify API, JavaScript client, Python client or CLI. Export the default Dataset as JSON, CSV or Excel, and open the authoritative run summary for coverage, delivered counts, charge information and state status.

After the Actor is public, you can create your own Apify Task or schedule from any successful input. No public Task or schedule is bundled with the Actor.

⚠️ Not yet supported

• Category and market pagination beyond the first verified page.
• Public review-row delivery.
• Non-US market coverage.
• Live workloads beyond the release-canary bounds: one US keyword target with maxListings: 25, one exact listing detail, or one public shop target with maxListings: 25 and one shop profile.
• Guaranteed population of cart, recent-purchase or sponsored fields.
• A naturally occurring live NEW or UPDATED observation; the same production parser, normalizer, diff, delivery and state path is verified with controlled source-shaped changes.
• Universal coverage across every keyword, shop, listing, locale or conditional Etsy field.
• Login, account data, imported cookies, private seller analytics, buyer identity, checkout actions or messages.
• CAPTCHA interaction or solving.
• Official API surfaces that require a buyer-supplied key or token.
• AI-generated demand, sales, popularity, quality, sentiment, value or recommendation scores.
• Deletion, sold, inactive or unavailable claims inferred from disappearance.

❓ FAQ and support

Why is a field null?

Etsy does not publish every field on every listing, shop or page. null means not observed; it is not an estimate or zero.

Does Detailed charge both listing events?

No. A successfully enriched row uses detailed_listing_result instead of listing_result.

Can a missing search result trigger deletion?

No. It becomes a free NOT_OBSERVED notice only when the comparison is otherwise compatible. The prior state is retained.

What should I include in a support request?

Send the Actor run ID, selected workflow, sanitized input and the coverage warning or stop reason. Remove API tokens and private data before sharing.