# Etsy Shop Scraper — Full Catalog Export (`astravalabs/etsy-shop-catalog-scraper`) Actor

Export complete Etsy product catalogs from up to 50 shops per run. Get listing IDs, titles, localized prices, images, URLs, and catalog positions with exact per-shop and whole-run result caps. No proxy setup or separate user start charge.

- **URL**: https://apify.com/astravalabs/etsy-shop-catalog-scraper.md
- **Developed by:** [astravalabs](https://apify.com/astravalabs) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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 Shop Scraper — Full Catalog Export

Export the complete product catalog from one Etsy shop or up to 50 shops in one
run. Get one clean row per listing with its title, localized price, image, URL,
catalog position, listing ID, and shop ID—without configuring proxies or CAPTCHA
handling.

Use it for competitor catalog tracking, assortment analysis, pricing research,
seller discovery, or as the first stage of a larger Etsy data pipeline.

### Quick start

```json
{
  "shops": [
    "ArtFablePets",
    "https://www.etsy.com/shop/WilshireGoodsShop"
  ],
  "country": "US",
  "maxTotalResults": 5000
}
```

`shops` accepts bare shop names and full Etsy shop URLs. Duplicates and blank
values are removed before the run starts.

### What you get

Each default-dataset row represents one catalog listing:

```json
{
  "shop": "ArtFablePets",
  "shop_id": 16875973,
  "listing_id": "1234567890",
  "title": "Personalized pet portrait",
  "url": "https://www.etsy.com/listing/1234567890/personalized-pet-portrait",
  "price": 24.95,
  "currency": "USD",
  "image_url": "https://i.etsystatic.com/.../il_794xN.jpg",
  "position": 1,
  "scraped_at": "2026-07-18T10:00:00+00:00"
}
```

Export the dataset as JSON, CSV, Excel, XML, RSS, or JSONL. Listing IDs can be
passed directly to the companion Etsy Product Scraper for product-page details,
variations, demand signals, shipping, and policies.

### Inputs and cost controls

| Input | Default | Description |
|---|---:|---|
| `shops` | required | 1–50 unique Etsy shop names or URLs |
| `maxTotalResults` | `5000` | Exact whole-run ceiling across every submitted shop |
| `maxListings` | all | Per-shop ceiling; `0` or omitted means paginate until that catalog ends |
| `catalogSort` | `custom` | Shop order, newest, price low/high, or relevance |
| `country` | `US` | Localizes returned prices and currency; 32 countries supported |

The two limits work together. For example, `maxListings: 100` and
`maxTotalResults: 1000` means no shop can contribute more than 100 rows and the
entire batch can never save more than 1,000. Raise `maxTotalResults` when you
intentionally want more than the default 5,000 rows.

The actor also stops cleanly if your Apify run spending limit is reached. The
dataset and `RUN_REPORT` reflect the number actually persisted, including when
Apify accepts only part of the final batch.

### Pricing

The price is **$3 per 1,000 saved listings** ($0.003 per result). There is no
separate actor-start charge to the user, and proxy handling is included.

| Saved results | Result charge |
|---:|---:|
| 100 | $0.30 |
| 1,000 | $3.00 |
| 5,000 (default whole-run cap) | $15.00 |

You pay only for rows saved to the dataset. `RUN_REPORT` is stored separately
and is not a billed result.

### Speed and scale

Shops run in parallel with one proxy session per active shop; pages inside a
shop remain sequential for session stability. Live local measurements used the
same 36-listing-per-shop workload for every concurrency comparison:

| Run shape | Time range | Listings | Successful samples |
|---|---:|---:|---:|
| 1 shop × up to 36 listings | 4.6–14.5s | 36 | 2/2 |
| 10 shops × up to 36 listings | 6.2–8.9s | 328 | 2/2 |
| 50 shops × up to 36 listings | 8.0–10.5s | 1,720 | 2/2 |

In the 50-shop concurrency comparison, all 8 runs across 8, 16, 25, and 50
workers completed 1,720/1,720 rows with zero failed shops. Fifty workers was
fastest on average at 9.29 seconds. Times vary with proxy warmup, Etsy response
latency, catalog size, and pagination depth.

### Sorting examples

Get the newest 25 products from each shop:

```json
{
  "shops": ["ArtFablePets", "WilshireGoodsShop"],
  "catalogSort": "date_desc",
  "maxListings": 25,
  "maxTotalResults": 50
}
```

Get prices as shown to a visitor in Germany:

```json
{
  "shops": ["ArtFablePets"],
  "country": "DE"
}
```

### Run status and partial results

The key-value store record `RUN_REPORT` preserves input order and gives each
shop an explicit status:

- `completed` — the catalog ended normally or reached `maxListings`.
- `capped` — the shop stopped at `maxTotalResults` or the Apify spending limit.
- `not_started` — the whole-run limit was already reached before this shop began.
- `failed` — shop resolution, retry recovery, pagination safety, or storage failed.

It also includes per-shop listing/page counts, the termination reason, run
totals, concurrency, proxy sessions, recoveries, and fetch outcomes. Rows saved
before a later page failure remain available and are counted accurately.

### API example

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/astravalabs~etsy-shop-scraper/run-sync-get-dataset-items?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shops":["ArtFablePets"],"maxListings":100}'
```

For larger jobs, start the Actor asynchronously and read the default dataset
after the run succeeds.

### Companion Etsy actors

- [Etsy Listings Scraper](https://apify.com/astravalabs/etsy-scraper) — discover listings in Etsy search and track ranks.
- [Etsy Product Scraper](https://apify.com/astravalabs/etsy-product-scraper) — enrich listing IDs with full product details, variations, shipping, and policies.
- [Etsy Reviews Scraper](https://apify.com/astravalabs/etsy-reviews-scraper) — export shop or listing review histories and seller responses.
- [Etsy Keyword Research Tool](https://apify.com/astravalabs/etsy-keyword-research-tool) — collect Etsy autocomplete keyword ideas.

### FAQ

**Does this include shop profile statistics or reviews?**

No. This actor is optimized for complete product catalogs. Use the Reviews
Scraper for buyer feedback and the Product Scraper for listing-level enrichment.

**Why did a shop return fewer rows than `maxListings`?**

`maxListings` is a ceiling, not a target. The actor stops when Etsy has no more
catalog items. Check `RUN_REPORT` for the exact status and reason.

**Can I scrape more than 5,000 listings?**

Yes. Set a higher `maxTotalResults`. The 5,000 default is a predictable cost
guardrail, not the technical catalog limit.

**Will duplicate listings be billed twice?**

Listings are deduplicated by ID within each shop before being saved.

> Unofficial. Not affiliated with, endorsed by, or sponsored by Etsy, Inc.
> “Etsy” is a trademark of Etsy, Inc., used here descriptively.

# Actor input Schema

## `shops` (type: `array`):

Etsy shops to scrape — either bare shop slugs ("ArtFablePets") or full shop URLs ("https://www.etsy.com/shop/ArtFablePets"). Both are reduced to the slug.

## `maxListings` (type: `integer`):

Cap catalog listings saved per shop. Leave empty (or 0) to scrape the whole catalog until pagination runs out. Set a value as a cost guardrail for large shops.

## `maxTotalResults` (type: `integer`):

Whole-run cap across all shops. The default 5,000-result ceiling makes the maximum result charge predictable even when several large catalogs are submitted together.

## `catalogSort` (type: `string`):

Order listings are fetched in. "Shop's order" is the owner's own arrangement (default). The others pair well with "Max listings" — e.g. Newest first to grab a shop's latest N products.

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

ISO-3166 country code — localizes the currency the catalog prices are shown in.

## Actor input object example

```json
{
  "shops": [
    "ArtFablePets"
  ],
  "maxTotalResults": 5000,
  "catalogSort": "custom",
  "country": "US"
}
```

# Actor output Schema

## `catalog` (type: `string`):

The dataset: one row per shop listing (title, price, image, URL, position).

## `runReport` (type: `string`):

Ordered per-shop status, termination reason, persisted listing/page counts, run totals, and retry diagnostics.

# 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 = {
    "shops": [
        "ArtFablePets"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("astravalabs/etsy-shop-catalog-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 = { "shops": ["ArtFablePets"] }

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

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

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

```

## CLI example

```bash
echo '{
  "shops": [
    "ArtFablePets"
  ]
}' |
apify call astravalabs/etsy-shop-catalog-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=astravalabs/etsy-shop-catalog-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/hi355VuNz8fxx1elu/builds/TH704eYUlkwZk30xk/openapi.json