# Etsy Scraper (`fetch_cat/etsy-scraper`) Actor

Export public Etsy listings and shops from searches, listing URLs, and shop URLs for pricing research, seller discovery, and catalog monitoring.

- **URL**: https://apify.com/fetch\_cat/etsy-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** E-commerce
- **Stats:** 3 total users, 2 monthly users, 95.2% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.32 / 1,000 saved records

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Etsy Scraper

Export public Etsy listings and seller metadata from product searches or public Etsy URLs. This Etsy data scraper creates a structured listing dataset for assortment research, pricing comparisons, seller discovery, and catalog monitoring, with an Etsy API workflow through Apify.

### What you get

- Canonical listing IDs, titles, URLs, images, displayed prices, currencies, availability, ratings, and seller links when public
- Public seller names and shop links on the associated listing records when Etsy exposes them
- Source URL, query/page position, and scrape timestamp for provenance
- Pagination, stable-ID deduplication, and a global persisted-record limit

### Example input

```json
{
  "searchQueries": ["linen apron"],
  "maxItems": 20,
  "includeDetails": true,
  "country": "US"
}
```

You can also provide public search, category, listing, or shop URLs:

```json
{
  "startUrls": [{ "url": "https://www.etsy.com/market/linen_apron" }],
  "maxItems": 10
}
```

### Input recipes

- **Search monitoring:** provide one or more `searchQueries`, set a low `maxItems`, and keep details enabled.
- **Listing lookup:** provide a public `/listing/…` URL in `startUrls`.
- **Shop catalog:** provide a public `/shop/…` URL in `startUrls` to export its visible listings, with public seller metadata on each listing when available.

### Input settings

| Field | Type | Description |
|---|---|---|
| `searchQueries` | string\[] | Etsy product searches to process. |
| `startUrls` | request\[] | Public Etsy search, category, listing, or shop URLs. |
| `maxItems` | integer | Global cap across successfully persisted listing rows. |
| `includeDetails` | boolean | Request public listing pages for additional listing/shop fields. |
| `country` | string | Two-letter ship-to country used for localization. |
| `proxyConfiguration` | object | Optional Apify Proxy configuration. |

At least one query or URL is required. Etsy account, messages, and other private URLs are rejected.

### Output

The Actor exposes one stable **default dataset** of listing records. Each record includes publicly visible seller identity and shop links when Etsy exposes them.

#### Listings

| Field | Description |
|---|---|
| `listingId`, `listingUrl` | Stable Etsy listing identity and canonical URL |
| `title`, `imageUrl` | Public product title and primary image |
| `shopName`, `shopUrl` | Public seller identity and link |
| `price`, `currencyCode`, `availability` | Displayed offer data |
| `rating`, `reviewCount` | Public aggregate rating data; not individual reviews |
| `position`, `page`, `sourceQuery` | Search provenance |
| `sourceUrl`, `scrapedAt` | Requested source and extraction timestamp |

Conditional fields are omitted when Etsy does not expose them; the Actor does not invent unsupported values.

### Pricing

The Actor charges the `result` event once after each listing row is successfully stored. See the live [Pricing tab](https://apify.com/fetch_cat/etsy-scraper/pricing) for current plan-specific rates.

### Tips and limits

- Start with a low `maxItems` value to verify your target and expected fields.
- Enable detail enrichment only when you need fields beyond public result cards.
- Etsy can vary fields by target and locale and may challenge automated requests. Partial output already saved is preserved.
- This release does not return individual review records or private/login-only data.

### Who is it for?

- **Etsy sellers** comparing public prices, titles, and assortments in a niche
- **Marketplace analysts** building repeatable listing datasets for research
- **Sourcing teams** finding public shops and monitoring visible catalogs
- **Developers and automation teams** feeding Etsy data into APIs, agents, spreadsheets, or databases

### API usage

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/etsy-scraper').call({
  searchQueries: ['linen apron'],
  maxItems: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ['APIFY_TOKEN'])
run = client.actor('fetch_cat/etsy-scraper').call(run_input={
    'searchQueries': ['linen apron'],
    'maxItems': 20,
})
items = client.dataset(run['defaultDatasetId']).list_items().items
print(items)
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/fetch_cat~etsy-scraper/runs?token=$APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["linen apron"],"maxItems":20}'
```

### MCP and agents

Add the Actor to Claude-compatible clients:

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

Or add an MCP server configuration:

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

Example prompts:

- “Use Etsy Scraper to export 20 linen apron listings and compare displayed prices.”
- “Export listings from a public Etsy shop and return each listing’s source URL.”
- “Collect a small Etsy listing dataset for a daily catalog-monitoring workflow.”

### Integrations

Send Actor output to Google Sheets, n8n, Zapier, Make, webhooks, cloud storage, or your own database through Apify integrations. Use schedules for repeated monitoring and keep the input small until you confirm the target returns the fields you need.

### FAQ

#### Does it require an Etsy login?

No. The Actor is limited to publicly visible pages and fields.

#### Does `maxItems` apply to seller data separately?

No. `maxItems` caps persisted listing rows in the default dataset. Seller identity is included on the associated listing when publicly visible.

#### Does it export customer reviews?

No. This release exports public listing rating aggregates only, not individual review records.

#### How can I export Etsy listings and prices to CSV or Excel?

Run the Actor with a search or public URL, then export the default listing dataset from Apify as CSV, Excel, JSON, or JSONL.

#### Can I scrape public Etsy shops through an API or MCP?

Yes. Use the JavaScript, Python, cURL, or MCP examples above. The same input schema applies in the Console and through API calls.

#### How do I monitor Etsy listing prices over time?

Schedule repeated runs and store each export in your destination. Prices reflect what Etsy publicly displayed when each record was collected.

#### Why are some optional fields missing?

Etsy varies public fields by listing, shop, locale, and page type. Missing optional values are omitted rather than replaced with guesses.

### Related Actors

- [Amazon Products & Search Scraper](https://apify.com/fetch_cat/amazon-products-search-scraper)
- [eBay Scraper](https://apify.com/fetch_cat/ebay-scraper)
- [Walmart Scraper](https://apify.com/fetch_cat/walmart-scraper)
- [Google Shopping Scraper](https://apify.com/fetch_cat/google-shopping-scraper)
- [AliExpress Scraper](https://apify.com/fetch_cat/aliexpress-scraper)

### Support

For bugs or target-specific problems, open an issue from the Actor page and include the public input URL and run ID. Do not include Etsy credentials or private account data.

# Changelog

This Actor's version history is a separate document: https://apify.com/fetch\_cat/etsy-scraper/changelog.md

# Actor input Schema

## `searchQueries` (type: `array`):

One or more Etsy product searches.

## `startUrls` (type: `array`):

Public Etsy search, category, listing, or shop URLs.

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

Global cap on successfully persisted records.

## `includeDetails` (type: `boolean`):

Fetch publicly visible listing detail fields when available.

## `country` (type: `string`):

Two-letter ship-to country code used for public result localization.

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

Optional Apify Proxy settings.

## Actor input object example

```json
{
  "searchQueries": [
    "linen apron"
  ],
  "startUrls": [
    {
      "url": "https://www.etsy.com/market/linen_apron"
    }
  ],
  "maxItems": 20,
  "includeDetails": true,
  "country": "US"
}
```

# Actor output Schema

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

No description

# 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 = {
    "searchQueries": [
        "linen apron"
    ],
    "startUrls": [
        {
            "url": "https://www.etsy.com/market/linen_apron"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/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 = {
    "searchQueries": ["linen apron"],
    "startUrls": [{ "url": "https://www.etsy.com/market/linen_apron" }],
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/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 '{
  "searchQueries": [
    "linen apron"
  ],
  "startUrls": [
    {
      "url": "https://www.etsy.com/market/linen_apron"
    }
  ]
}' |
apify call fetch_cat/etsy-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetch_cat/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/Oe8nbbWMlsCyMOPQR/builds/uKHGrwVsKf0ytD7Js/openapi.json