# Etsy Scraper (`automation-lab/etsy-scraper`) Actor

Scrape Etsy listings for handmade and vintage marketplace price monitoring. Extract names, prices, shops, ratings, images, and availability from search results.

- **URL**: https://apify.com/automation-lab/etsy-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** E-commerce, Lead generation
- **Stats:** 898 total users, 113 monthly users, 99.8% runs succeeded, 7 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.95 / 1,000 product scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Etsy Scraper

Scrape [Etsy](https://www.etsy.com) product listings at scale for handmade, vintage, and creator-marketplace price intelligence. Extract product names, prices, shop names, ratings, images, availability, and more from Etsy search results — no API keys, no login, no manual copying required.

This actor searches Etsy through query-specific market URLs, bypassing DataDome anti-bot protection that blocks standard `/search` endpoints. It uses lightweight HTTP requests with Cheerio (no browser) and parses structured data and listing cards embedded in Etsy pages, giving you clean, structured product data in seconds.

### What does Etsy Scraper do?

**Etsy Scraper** extracts product listing data from [Etsy](https://www.etsy.com) search results. Use it for handmade and vintage marketplace price monitoring, competitor listing research, and niche assortment tracking. You provide a specific search query (like `handmade leather wallet` or `vintage engagement ring`), and the scraper returns structured data for matching products — ready to export in JSON, CSV, or Excel.

🔍 **Search any Etsy query** — from `boho wedding decor` to `custom pet portrait`
📦 **Up to 5,000 products per run** — paginate through dozens of result pages automatically
🏷️ **Filter by price, shipping, and sale status** — narrow results before scraping
⚡ **Fast and lightweight** — HTTP-only with Cheerio, no browser overhead
🛡️ **Bypasses DataDome** — uses query-specific market URL patterns that avoid anti-bot blocks
💰 **Pay per result** — $0.003 per product extracted, no monthly subscription

### Who is it for?

**🛒 Handcraft sellers and Etsy shop owners**
You're running your own Etsy shop and need competitive intelligence to price and position your products.

- Monitor competitor pricing in your niche (jewelry, decor, apparel, etc.)
- Track which keywords and product titles competitors are ranking for
- Identify pricing sweet spots and gaps in the market

**📊 Dropshippers and product sourcers**
You're building a store and looking for trending handmade or vintage products to resell.

- Find top-selling products by scraping with `sort: recently_listed` or `sort: most_relevant`
- Identify prolific shops to approach as suppliers
- Track which product niches have the best sale-to-stock ratio

**📈 Market researchers and competitive analysts**
You're studying Etsy as a handmade/vintage marketplace — pricing trends, niche demand, or market saturation.

- Extract pricing distributions across Etsy niches and specific search terms
- Measure listing density and competition for handmade, vintage, digital, or craft-supply searches
- Build time-series datasets by scheduling daily runs

**🤖 Data engineers and developers**
You need Etsy product data piped into your application, database, or analytics pipeline.

- Integrate via Apify API with Node.js, Python, or cURL
- Schedule automated daily or weekly runs without writing any scraping code
- Feed results into Google Sheets, Airtable, Notion, or any webhook endpoint

### Why use Etsy Scraper?

🚫 **No Etsy API limitations** — Etsy's official API requires OAuth approval, has strict rate limits, and restricts access to search results. This scraper extracts the same data directly from public pages with no API key needed.

⚙️ **No browser required** — unlike Playwright-based scrapers, Etsy Scraper uses pure HTTP requests with Cheerio parsing. Lower compute costs, faster execution, and higher reliability.

🛡️ **DataDome bypass built in** — Etsy's `/search` endpoint is protected by DataDome bot detection. This scraper routes through query-specific `/market/{query}` paths that return product data without triggering blocks.

📋 **LD+JSON extraction** — product data is parsed from Google-structured LD+JSON embedded in the HTML, not fragile CSS selectors. Consistent, reliable output even when Etsy updates their page design.

🔄 **Automatic retry and rotation** — failed requests are retried up to 5 times with exponential backoff and fresh residential proxy sessions on each attempt.

🌐 **256 MB footprint** — HTTP-only actor with minimal memory use, keeping platform costs extremely low and runs fast.

💵 **Transparent pay-per-result pricing** — you pay only for products actually extracted, plus a tiny $0.005 startup fee. No upfront credits, no monthly lock-in.

### What data can you extract from Etsy?

Each scraped product includes base fields covering listing identity, pricing, seller info, shipping status, and product type. Enable `enrichListingDetails` to append nullable listing-page intelligence fields:

| Field | Type | Description |
|-------|------|-------------|
| `listingId` | String | Unique Etsy listing identifier |
| `name` | String | Product title as shown on Etsy |
| `url` | String | Direct link to the product listing |
| `imageUrl` | String | Main product image URL |
| `shop` | String | Seller shop name |
| `shopId` | String | Unique shop identifier |
| `price` | String | Current listing price in the selected currency |
| `originalPrice` | String | Pre-sale price (if discounted), else `null` |
| `currency` | String | Price currency code (e.g., USD, EUR, AUD) |
| `onSale` | Boolean | Whether the item is currently on sale |
| `freeShipping` | Boolean | Whether free shipping is offered |
| `rating` | Number | Star rating (1.0–5.0), `null` if unrated |
| `reviewCount` | Number/null | Review count shown beside the search-card rating, `null` when unavailable |
| `availability` | String | Stock status (e.g., "In Stock") |
| `isDigitalDownload` | Boolean | Whether the listing is a digital download (e.g., printable, STL, pattern) |
| `hasVariations` | Boolean | Whether the listing appears to have selectable variants |
| `priceMayBeMinimumVariant` | Boolean | Whether the shown price appears to be the lowest variant price (for example Etsy's "from $12" cue) |
| `variantDetectionStatus` | String | `listing_page` when confirmed from the listing page, otherwise `search_card_fallback` |
| `detailEnrichmentStatus` | String | `enriched` or `unavailable`; present only when detail enrichment is enabled |
| `sellerSales` | Number/null | Public seller sales count when available |
| `sellerReviewCount` | Number/null | Public seller review count when available |
| `inCartCount` | Number/null | Current public in-cart social-proof count when available |
| `boughtInLast24Hours` | Number/null | Public recent-purchase count when available |
| `tags` | Array/null | Listing tags when available |
| `materials` | Array/null | Listed materials when available |
| `shipping` | String/null | Public delivery/shipping text when available |
| `personalization` | String/null | Personalization instructions when available |
| `position` | Number | Result position in search results |
| `query` | String | The search query that produced this listing |
| `page` | Number | Which results page this listing came from |
| `scrapedAt` | String | ISO 8601 timestamp of extraction |

### How much does it cost to scrape Etsy listings?

Etsy Scraper uses **pay-per-event** pricing — you pay only for what you scrape. No monthly subscription. All platform costs are included.

For large query-based scrapes, set **Maximum charge per run** in Apify before starting. The actor checks charge limits as it runs and stops early once the cap is reached.

| | FREE | BRONZE | SILVER | GOLD | PLATINUM | DIAMOND |
|---|---|---|---|---|---|---|
| **Per run** | $0.005 | $0.00475 | $0.00425 | $0.00375 | $0.003 | $0.0025 |
| **Per product** | $0.003 | $0.0027 | $0.0024 | $0.00195 | $0.0015 | $0.0012 |
| **1,000 products** | $3.005 | $2.705 | $2.405 | $1.954 | $1.503 | $1.203 |

Tier discounts are applied automatically based on your Apify subscription plan. Higher tiers receive lower per-product rates.

**Real-world cost examples (FREE tier):**

| Use case | Products | Duration | Cost |
|---|---|---|---|
| Quick niche check | 20 products | ~5 sec | ~$0.065 |
| Single niche query | 64 products | ~15 sec | ~$0.197 |
| Competitor analysis | 200 products | ~45 sec | ~$0.605 |
| Market research snapshot | 500 products | ~2 min | ~$1.505 |
| Large-scale extraction | 1,000 products | ~4 min | ~$3.005 |
| Full niche deep-dive | 5,000 products | ~20 min | ~$15.005 |

💡 The **free tier** includes $5 of monthly usage — enough to scrape ~1,400 products at no cost.

### How to scrape Etsy products step by step

1. **Go to [Etsy Scraper](https://apify.com/automation-lab/etsy-scraper) on Apify Store** and click **"Try for free"**. Sign up for an Apify account if you don't have one — the free tier includes $5 of monthly usage.

2. **Enter your search query** in the "Search Query" field. Use the same terms you'd type into Etsy's search bar, for example: `handmade leather journal`, `vintage gold ring`, or `custom pet portrait`.

3. **Use a specific query** that includes the niche you need, such as `handmade silver necklace` or `personalized wedding gift`. Etsy market pages use the query itself for relevance.

4. **Set the maximum number of products** you want. The default is 64. Increase up to 5,000 for large-scale extraction; the number Etsy makes available varies by query.

5. **Apply optional filters** — set a price range with `minPrice` / `maxPrice`, restrict to free shipping only, or filter to on-sale items only. Choose a sort order: Most Relevant, Lowest Price, Highest Price, or Recently Listed.

6. **Configure proxy settings.** Residential proxy is pre-selected and required. Etsy actively blocks datacenter IPs — do not change the proxy group unless you have your own residential proxy provider.

7. **Click "Start"** and wait for the run to complete. A typical 64-product run finishes in under 30 seconds.

8. **Download your data** from the Dataset tab in JSON, CSV, Excel, or other formats. You can also connect results directly to Google Sheets, Slack, Airtable, or any webhook endpoint.

**Example input for a basic search:**

```json
{
    "searchQuery": "handmade necklace",
    "maxItems": 100,
    "sort": "most_relevant"
}
```

**Example input for sale + free shipping filter:**

```json
{
    "searchQuery": "vintage leather bag",
    "maxItems": 200,
    "sort": "lowest_price",
    "onSale": true,
    "freeShipping": true,
    "maxPrice": 80,
    "enrichListingDetails": true
}
```

### Input parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `searchQuery` | String | ✅ Yes | — | What to search for on Etsy (e.g., `handmade necklace`) |
| `maxItems` | Integer | No | 64 | Maximum number of products to scrape (1–5,000) |
| `sort` | String | No | `most_relevant` | Sort order: `most_relevant`, `lowest_price`, `highest_price`, `recently_listed` |
| `minPrice` | Number | No | — | Minimum price filter in the selected currency |
| `maxPrice` | Number | No | — | Maximum price filter in the selected currency |
| `freeShipping` | Boolean | No | `false` | Only return products with free shipping |
| `onSale` | Boolean | No | `false` | Only return products currently on sale |
| `currency` | String | No | `USD` | ISO 4217 currency code for prices (e.g., `USD`, `EUR`, `GBP`, `CAD`, `AUD`). All prices in results will be in this currency. |
| `locale` | String | No | `en-US` | BCP 47 locale code for the language of results (e.g., `en-US`, `de-DE`, `fr-FR`). Affects listing titles and labels. |
| `excludeDigitalDownloads` | Boolean | No | `false` | Remove digital download listings (printables, STL files, patterns) from results. Uses Etsy's `item_type=physical` filter plus post-extraction detection. |
| `excludeKeywords` | Array | No | — | Skip any listing whose title contains one of these keywords (case-insensitive). Example: `["STL", "digital", "download"]`. Applied before `includeKeywords`. |
| `includeKeywords` | Array | No | — | Only keep listings whose title contains at least one of these keywords (case-insensitive). Example: `["handmade", "vintage"]`. Applied after `excludeKeywords`. |
| `enrichListingDetails` | Boolean | No | `false` | Fetch each listing page and append nullable seller sales/reviews, cart and recent-purchase signals, tags, materials, shipping, and personalization. Detail runs are slower; blocked or absent values remain `null`. |
| `proxyConfiguration` | Object | No | Residential | Proxy settings. Residential proxy strongly recommended for Etsy |

### Output example

Each product in the dataset looks like this:

```json
{
    "listingId": "1284957302",
    "name": "Handmade Gold Filled Necklace, Dainty Chain Necklace, Gift for Her",
    "url": "https://www.etsy.com/listing/1284957302/handmade-gold-filled-necklace-dainty",
    "imageUrl": "https://i.etsystatic.com/12345678/r/il/abc123/4567890123/il_300x300.4567890123_example.jpg",
    "shop": "GoldenChainCo",
    "shopId": "34521890",
    "price": "24.99",
    "originalPrice": null,
    "currency": "USD",
    "onSale": false,
    "freeShipping": true,
    "rating": 4.8,
    "reviewCount": 1234,
    "availability": "In Stock",
    "isDigitalDownload": false,
    "hasVariations": true,
    "priceMayBeMinimumVariant": true,
    "variantDetectionStatus": "search_card_fallback",
    "position": 1,
    "query": "handmade necklace",
    "page": 1,
    "scrapedAt": "2026-03-22T14:30:00.000Z"
}
```

**Sale item with original price:**

```json
{
    "listingId": "4428738695",
    "name": "Orchid Pearl Necklace, Real Orchid Pendant, Handmade Botanical Jewellery",
    "url": "https://www.etsy.com/listing/4428738695/orchid-pearl-necklace-real-orchid",
    "imageUrl": "https://i.etsystatic.com/63062527/r/il/d7e81d/7578438711/il_fullxfull.7578438711_7a2q.jpg",
    "shop": "ZivaJewelleryArt",
    "shopId": "63062527",
    "price": "49.64",
    "originalPrice": "62.05",
    "currency": "AUD",
    "onSale": true,
    "freeShipping": false,
    "rating": 5,
    "availability": "In Stock",
    "isDigitalDownload": false,
    "hasVariations": false,
    "priceMayBeMinimumVariant": false,
    "variantDetectionStatus": "search_card_fallback",
    "position": 3,
    "query": "handmade necklace",
    "page": 1,
    "scrapedAt": "2026-03-23T00:50:47.547Z"
}
```

### Tips for best results

🏷️ **Use a specific niche query** — the scraper uses Etsy's `/market/` URL, where the query determines relevance. `vintage leather messenger bag` produces a more focused dataset than `bag`, and available result depth varies by query.

🔑 **Use specific search terms** — `vintage leather messenger bag` returns far more relevant results than just `bag`. Etsy's search engine rewards specificity with better product matches.

💰 **Combine price filters with sort order** — to find the cheapest items in a niche, set `sort: lowest_price` and `maxPrice: 50`. This is the most effective setup for competitive pricing analysis.

📦 **Filter free shipping for buyer-perspective research** — many Etsy shoppers filter for free shipping. Use the `freeShipping: true` filter to see exactly what those buyers see — useful for optimizing your own listings.

🔄 **Schedule daily runs for price monitoring** — use Apify Schedules to run this scraper automatically. Export to Google Sheets and track price changes over time in any niche.

⚠️ **Start small to validate your query** — run 20–100 products first to confirm the search term returns what you expect. Then scale up to 500–5,000 once you're satisfied with the data quality.

🌐 **Residential proxy is non-negotiable** — Etsy blocks datacenter and shared proxy IPs. The actor is pre-configured with `RESIDENTIAL` proxy group. Do not change this unless you have a specific residential proxy provider configured.

📅 **Use `recently_listed` sort for trend spotting** — set sort to `recently_listed` to catch new products for a query as soon as they appear. Combine with a scheduled run to monitor emerging trends.

### Integrations

Etsy Scraper works with Apify's full integration ecosystem. Here are concrete workflow patterns:

📊 **Google Sheets price tracker** — connect the dataset output to Google Sheets via Apify's native integration. Run the scraper on a daily schedule to build a rolling price history for any Etsy niche. Spot price trends without touching a spreadsheet.

💬 **Slack alerts for new listings** — combine `sort: recently_listed` with a Slack notification. Get automatically pinged when new products appear for your target query — useful for dropshippers and sourcing teams.

📧 **Email reports to your team** — use Apify's email integration to send a daily CSV export of competitor product data directly to stakeholders — no manual downloads.

🗄️ **Database sync** — push results to PostgreSQL, MySQL, MongoDB, or Airtable via Apify webhooks. Build a product intelligence database that updates on a schedule.

📁 **Amazon S3 / Google Cloud Storage** — archive datasets automatically to cloud storage for long-term trend analysis or compliance.

🔗 **Zapier and Make** — trigger downstream workflows in 5,000+ apps. Examples: automatically add new Etsy products to a Notion database, update a CRM with competitor listings, or push data to a Slack channel on schedule.

🐍 **Python and Node.js** — use the Apify SDK to call this actor programmatically and process results in your own pipeline (see API usage below).

### Using the Apify API

You can call Etsy Scraper programmatically using the Apify API. Here are examples in Node.js, Python, and cURL.

#### Node.js

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('automation-lab/etsy-scraper').call({
    searchQuery: 'handmade ceramic mug',
    maxItems: 100,
    sort: 'most_relevant',
    freeShipping: true,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(`Found ${items.length} products`);
items.forEach((item) => {
    console.log(`${item.name} — $${item.price} by ${item.shop}`);
});
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("automation-lab/etsy-scraper").call(run_input={
    "searchQuery": "vintage engagement ring",
    "maxItems": 200,
    "sort": "lowest_price",
    "minPrice": 50,
    "maxPrice": 500,
})

dataset = client.dataset(run["defaultDatasetId"]).list_items().items
for product in dataset:
    print(f"{product['name']} — ${product['price']} ({product['shop']})")
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/automation-lab~etsy-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQuery": "custom wedding invitation",
    "maxItems": 50,
    "sort": "most_relevant"
  }'
```

Retrieve results after the run completes:

```bash
curl "https://api.apify.com/v2/datasets/DATASET_ID/items?token=YOUR_APIFY_TOKEN&format=json"
```

### Use with AI agents via MCP

Etsy Scraper is available as a tool for AI assistants that support the [Model Context Protocol (MCP)](https://docs.apify.com/platform/integrations/mcp).

Add the Apify MCP server to your AI client — this gives you access to all Apify actors, including this one:

#### Setup for Claude Code

```bash
claude mcp add --transport http apify "https://mcp.apify.com/?tools=automation-lab/etsy-scraper"
```

#### Setup for Claude Desktop, Cursor, or VS Code

Add this to your MCP config file:

```json
{
    "mcpServers": {
        "apify": {
            "url": "https://mcp.apify.com/?tools=automation-lab/etsy-scraper"
        }
    }
}
```

Your AI assistant will use OAuth to authenticate with your Apify account on first use.

#### Example prompts

Once connected, try asking your AI assistant:

- "Use automation-lab/etsy-scraper to find the 50 most relevant handmade silver rings under $100 with free shipping and export results as a table."
- "Search Etsy for vintage denim jackets, sorted by lowest price, and summarize the price range and top shops."
- "Find the 20 most recently listed custom wedding invitations on Etsy and list each product name, shop, and price."

Learn more in the [Apify MCP documentation](https://docs.apify.com/platform/integrations/mcp).

### Is it legal to scrape Etsy?

Etsy Scraper accesses only publicly available product listing data from Etsy search results — the same information any visitor sees when browsing [etsy.com](https://www.etsy.com). No login, no authentication, and no private data access is involved.

Scraping publicly available web data is generally legal based on the 2022 US Ninth Circuit ruling in *hiQ Labs v. LinkedIn*, which established that scraping public data does not violate the Computer Fraud and Abuse Act (CFAA). The European Court of Justice has similarly held that publicly available data can be lawfully collected.

However, you should:

⚖️ **Review Etsy's Terms of Service** before scraping at scale — while public data extraction is broadly legal, Etsy's ToS may restrict automated access. Compliance with ToS is your responsibility.

🔒 **Never collect personal data without lawful basis** — this actor extracts only product and shop data, not buyer or payment information.

📏 **Be respectful with volume** — the scraper includes built-in delays between pages (1.5 seconds) and respects rate limits. Avoid running dozens of concurrent large-scale scrapes.

🏢 **Consult legal counsel** if you plan to use scraped data commercially at scale, especially across jurisdictions with varying data protection regulations.

For more details, see Apify's guide on [web scraping legality](https://blog.apify.com/is-web-scraping-legal/).

### FAQ

**Why did the run return fewer products than `maxItems`?**
Etsy controls how many listings its `/market/` pages expose for each query. Use a more specific or alternate query, and treat `maxItems` as an upper bound rather than a guaranteed count.

**What happened to the old `category` input?**
It was removed from the input form because Etsy's working market route cannot apply it and the field did not change results. Existing saved integrations that still send `category` remain query-based; remove that property and include the niche in `searchQuery` instead.

**Can I scrape individual Etsy product detail pages?**
No. This scraper extracts data from Etsy search result pages only. Individual listing pages (`/listing/123456`) use heavy JavaScript rendering and more aggressive DataDome protection that requires a browser-based approach. The search results provide comprehensive product data including price, rating, shop, and availability — sufficient for most research use cases.

**Why do some products have `null` for `rating` or `reviewCount`?**
Products that have not yet received reviews do not display rating signals on Etsy. The scraper returns `null` instead of a misleading zero. Etsy can also omit a review count even when a rating is visible, so `reviewCount` independently remains `null` whenever the search card does not expose it.

**How reliable are `hasVariations` and `priceMayBeMinimumVariant`?**
The scraper first tries to confirm variants from the listing page. Etsy sometimes blocks listing-detail pages more aggressively than search pages, so the scraper falls back to search-card signals such as Etsy's "from $12" minimum-price label and title cues like "choose", "customizable", "colors", or "sizes". `variantDetectionStatus` tells you which source was used. The fields are always boolean so `false` means "no variant signal found" rather than an ambiguous `null`.

**The scraper returned "blocked" warnings. What should I do?**
Ensure you're using residential proxies (the default configuration). If blocks persist, try reducing `maxItems` or waiting a few minutes before retrying. Etsy's anti-bot detection can be more aggressive during peak traffic hours. The scraper automatically retries each request up to 5 times with fresh proxy sessions — occasional blocks are handled transparently.

**How is this different from the official Etsy API?**
The official Etsy API requires an approved OAuth application, enforces strict rate limits, and does not expose search result pages. This scraper extracts the same data any browser visitor sees from public search pages, with no API key required, no rate limit approvals, and no OAuth setup.

**How often can I run this scraper?**
There's no run frequency limit from the scraper side. Use Apify Schedules to run hourly, daily, or weekly. For price monitoring, daily runs are typically sufficient and keep costs low. You can also trigger runs via API as part of a larger pipeline.

### Related actors

🛒 [Amazon Scraper](https://apify.com/automation-lab/amazon-scraper) — Extract product data, prices, ratings, and seller info from Amazon search results

🏷️ [eBay Scraper](https://apify.com/automation-lab/ebay-scraper) — Scrape eBay product listings, prices, bids, and seller information

🛒 [Walmart Scraper](https://apify.com/automation-lab/walmart-scraper) — Scrape Walmart product data, prices, and availability

📋 [Craigslist Scraper](https://apify.com/automation-lab/craigslist-scraper) — Scrape Craigslist listings by keyword and city

🛍️ [Shopify Store Scraper](https://apify.com/automation-lab/shopify-scraper) — Monitor direct-to-consumer Shopify competitor catalogs, prices, availability, and reviews

👗 [Poshmark Scraper](https://apify.com/automation-lab/poshmark-scraper) — Extract fashion and resale listings from Poshmark

💻 [Newegg Scraper](https://apify.com/automation-lab/newegg-scraper) — Scrape electronics and tech products from Newegg

🔎 [Google Shopping Scraper](https://apify.com/automation-lab/google-shopping-scraper) — Scrape Google Shopping results for cross-marketplace price comparison

🎯 [Fiverr Scraper](https://apify.com/automation-lab/fiverr-scraper) — Extract Fiverr gig listings, seller info, and pricing for service marketplace research

# Actor input Schema

## `searchQuery` (type: `string`):

What to search for on Etsy (e.g., 'handmade jewelry', 'vintage dress', 'custom gift').

## `maxItems` (type: `integer`):

Maximum number of products to scrape.

## `sort` (type: `string`):

How to sort search results.

## `minPrice` (type: `number`):

Minimum price filter (in the selected currency).

## `maxPrice` (type: `number`):

Maximum price filter (in the selected currency).

## `freeShipping` (type: `boolean`):

Only show products with free shipping.

## `onSale` (type: `boolean`):

Only show products that are on sale.

## `currency` (type: `string`):

ISO 4217 currency code to use for prices (e.g. USD, EUR, GBP, CAD, AUD). Etsy will convert all prices to this currency, so results are consistent and comparable.

## `locale` (type: `string`):

BCP 47 locale code for the language of results (e.g. en-US, en-GB, de-DE, fr-FR). Affects listing titles and labels returned by Etsy.

## `excludeDigitalDownloads` (type: `boolean`):

When enabled, digital download listings (STL files, printables, patterns, etc.) are removed from results. Uses Etsy's server-side item\_type=physical filter plus a post-extraction check.

## `excludeKeywords` (type: `array`):

Skip any listing whose title contains one of these keywords (case-insensitive). Useful for removing digital or unwanted items. Example: \["STL", "digital", "download", "print file"].

## `includeKeywords` (type: `array`):

Only keep listings whose title contains at least one of these keywords (case-insensitive). Applied after excludeKeywords. Example: \["3D printed", "articulated", "flexi"].

## `enrichListingDetails` (type: `boolean`):

Fetch each listing page and append seller sales/reviews, cart and recent-purchase signals, tags, materials, shipping, and personalization when publicly available. This is slower than search-only extraction and unavailable values are returned as null.

## `proxyConfiguration` (type: `object`):

Proxy settings. Residential proxies recommended for Etsy.

## Actor input object example

```json
{
  "searchQuery": "handmade necklace",
  "maxItems": 20,
  "sort": "most_relevant",
  "minPrice": 10,
  "maxPrice": 100,
  "freeShipping": false,
  "onSale": false,
  "currency": "USD",
  "locale": "en-US",
  "excludeDigitalDownloads": false,
  "excludeKeywords": [
    "digital",
    "download"
  ],
  "includeKeywords": [
    "handmade"
  ],
  "enrichListingDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

Etsy listings emitted by this run.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "searchQuery": "handmade necklace",
    "maxItems": 20,
    "excludeKeywords": [
        "digital",
        "download"
    ],
    "includeKeywords": [
        "handmade"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/etsy-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "searchQuery": "handmade necklace",
    "maxItems": 20,
    "excludeKeywords": [
        "digital",
        "download",
    ],
    "includeKeywords": ["handmade"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/etsy-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "searchQuery": "handmade necklace",
  "maxItems": 20,
  "excludeKeywords": [
    "digital",
    "download"
  ],
  "includeKeywords": [
    "handmade"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call automation-lab/etsy-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/etsy-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/DpTUzMvbQpfdogIyK/builds/d3ZAxkH28lBOgQbMt/openapi.json