# Etsy Scraper | Listings Shops Categories Prices (`lentic_clockss/etsy-scraper`) Actor

Scrape Etsy.com listings, shops & categories — keyword search, nested PLPs, PDP enrich, multi-market ship-to. Extract listingId, prices, ratings, images, badges. Export Excel/CSV/JSON.

- **URL**: https://apify.com/lentic\_clockss/etsy-scraper.md
- **Developed by:** [kane liu](https://apify.com/lentic_clockss) (community)
- **Categories:** E-commerce, Lead generation, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use 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 | Listings Shops Categories Prices

**Scrape Etsy product listings, keyword search, shops, categories, featured hubs, and listing detail pages — then download structured marketplace data as Excel, CSV, or JSON.**

Use this Actor as a practical **Etsy product data API** for price monitoring, seller research, and handmade/vintage assortment tracking. Pick a **ship-to market**, choose a mode, set filters, and get Dataset rows with `listingId`, prices (sale / original / % off), ratings, images, shop names, and ad badges.

- Scrape **Etsy search**, **shop search**, **category & subcategory PLPs** (`/c/jewelry` or `/c/jewelry/necklaces`), **listing PDP**, **shop pages**, **featured / curated** hubs, and the **category taxonomy**
- Cover **30+ ship-to markets** (US, GB, CA, AU, DE, FR, …) with locale, currency, and residential egress aligned to the market
- Extract **title, price, currency, salePrice, originalPrice, discountPercent, ratingValue, reviewCount, imageUrl, shopName, badges, isAd**
- Optional **PDP enrich** (`enrichDetails`) for shipping text, shop sales / years, more images, and variations
- Filter by **price range**, **ships from**, **ready to ship**, **Star Seller**, **free shipping**, and digital download
- Export to **Excel / CSV / JSON**, or connect Make, n8n, Zapier, Python, or the Apify API
- **Pay per event** — Actor start + each Dataset result; **platform usage is included** (you do not pay separate Apify compute on top)

> **Unofficial tool.** This Actor is not affiliated with, endorsed by, or sponsored by Etsy, Inc. It collects publicly reachable listing and shop surfaces and does **not** log in, checkout, place orders, or access private buyer/seller accounts. Login-only pricing and full review-pagination APIs are out of scope.

---

### What does the Etsy Scraper do?

[Etsy Scraper](https://apify.com/lentic_clockss/etsy-scraper) lets you **extract structured listing and shop data from [Etsy.com](https://www.etsy.com/)** without running your own anti-bot browser fleet. Give it a keyword, category slug, listing ID, shop name, or featured path, then start a run.

Under the hood, the Actor:

1. Validates your input (mode, ship-to market, query / category / listing / shop, filters)
2. Enforces free-tier caps when you are on a free Apify plan
3. Calls a managed Cloud Run worker that opens Etsy with residential egress and browser automation
4. Parses SERP cards (DOM + optional listingCards intercept) and PDP JSON-LD
5. Pushes Dataset rows ready for Excel / CSV / JSON export
6. Writes `RUN_SUMMARY` (and `ERROR_SUMMARY` on failure) to the key-value store

You run it like any other Apify Actor — schedule it, call it from the API, or plug it into automations.

---

### What Etsy data can I extract?

| Data | Search | Shop search | Category | Listing PDP | Shop | Featured | Categories |
| --- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
| listingId / URL | ✅ | — | ✅ | ✅ | ✅ | ✅ | — |
| Title / name | ✅ | shop | ✅ | ✅ | ✅ | ✅ | ✅ |
| Price / sale / original / % off | ✅ | — | ✅ | ✅ | ✅ | ✅ | — |
| Currency (by ship-to) | ✅ | — | ✅ | ✅ | ✅ | ✅ | — |
| shopName / shopUrl | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | — |
| imageUrl / images | ✅ | — | ✅ | ✅ | ✅ | ✅ | — |
| ratingValue / reviewCount | ✅ | — | ✅ | ✅ | shop meta | ✅ | — |
| badges / isAd | ✅ | — | ✅ | — | ✅ | ✅ | — |
| shipping / sales / years | enrich | — | enrich | ✅ | shop meta | enrich | — |
| variations / material | enrich | — | enrich | ✅ | — | enrich | — |
| categorySlug / path | — | — | ✅ | ✅ | — | — | ✅ |

---

### Why scrape Etsy?

Etsy is the leading marketplace for handmade, vintage, and craft goods. Teams scrape Etsy for **price monitoring**, **competitor analysis**, **product research**, and **seller lead generation**:

- Monitor **Etsy search results** and **category PLPs** across ship-to markets and currencies
- Track **sale vs original price**, discount %, Star Seller / ad badges, and ratings
- Pull **shop listings** with shop-level rating and sales text
- Map the **category taxonomy** (depth 2+) for assortment planning
- Enrich listings with **PDP JSON-LD** (images, availability, variations)
- Feed BI dashboards, pricing tools, or AI agents with structured Etsy rows

Compared with keyword-only Etsy scrapers, this Actor covers **search + shop search + nested categories + PDP enrich + shops + featured + taxonomy** with **multi-market ship-to prefs** in one input surface.

---

### How to scrape Etsy listings (no code required)

1. Create a free [Apify](https://apify.com/) account
2. Open [Etsy Scraper](https://apify.com/lentic_clockss/etsy-scraper)
3. Choose a **shipTo** market (e.g. `US`, `GB`, `AU`, `DE`)
4. Choose a **mode**: `search`, `search_shops`, `category`, `listing`, `shop`, `categories`, or `featured`
5. Enter a **query**, **categorySlug** (`jewelry` or `jewelry/necklaces`), **listingId**, **shopName**, or **featuredPath**
6. *(Optional)* Set `order`, `priceMin` / `priceMax`, `starSeller`, `readyToShip`, `shipsFrom`, `enrichDetails`, `maxResults`
7. Click **Start** and download the Dataset as JSON, CSV, Excel, or JSONL

Start with `maxResults: 5–10` to verify the query, then scale up.

---

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

This Actor uses **pay-per-event** pricing. You are charged for:

| Event | Price |
| --- | --- |
| Actor Start (`apify-actor-start`) | **$0.005** per start |
| Result (`apify-default-dataset-item`) | **$3.00 / 1,000** results (**$0.003** each) |

**Platform usage costs are included** — you do **not** pay separate Apify compute/proxy usage for this Actor on top of the event prices above (**User pays platform usage costs = No**).

#### Example cost estimates

| Results collected | Approx. event cost* |
| --- | ---: |
| 100 | ~$0.31 |
| 1,000 | ~$3.01 |
| 10,000 | ~$30.01 |

\*Assumes one Actor start at default memory billing for start events, plus `$0.003` per Dataset item. Exact start billing can scale with allocated memory (one start event per GB, minimum one).

#### Free plan limits

On a **free Apify plan**, this Actor enforces developer limits of **10 runs** and **200 results per run**. Upgrade to a paid Apify plan for unlimited runs (event prices still apply).

---

### Input examples

#### Keyword search (US)

```json
{
  "mode": "search",
  "query": "ceramic mug",
  "shipTo": "US",
  "maxResults": 40,
  "order": "price_asc",
  "starSeller": true
}
````

#### Nested category (GB)

```json
{
  "mode": "category",
  "categorySlug": "jewelry/necklaces",
  "shipTo": "GB",
  "order": "price_asc",
  "maxResults": 30
}
```

#### Listing PDP enrich

```json
{
  "mode": "listing",
  "listingId": "591039492",
  "shipTo": "US",
  "enrichDetails": true
}
```

#### Shop listings

```json
{
  "mode": "shop",
  "shopName": "hardwoodcase",
  "shipTo": "US",
  "maxResults": 50
}
```

#### Search shops / featured

```json
{
  "mode": "search_shops",
  "query": "woodworking",
  "shipTo": "US",
  "maxResults": 20
}
```

```json
{
  "mode": "featured",
  "featuredPath": "/featured/hub",
  "maxResults": 20
}
```

***

### Coverage matrix

| Dimension | Coverage |
| --- | --- |
| Host | `www.etsy.com` |
| Markets (`shipTo`) | 30+ ISO markets + `ROW` (prefs + proxyCountry) |
| Modes | `search` · `search_shops` · `category` · `listing` · `shop` · `categories` · `featured` |
| Category | `/c/{slug}` and nested `/c/{a}/{b}` |
| Sort | Verified: `most_relevant` · `price_asc` · `price_desc` · `date_desc` |
| Filters | price · instantDownload · shipsFrom · readyToShip · starSeller · freeShipping |
| Enrich | PDP JSON-LD + shipping / sales / years / images / variations |
| Identity | `listingId` |

***

### Output example

```json
{
  "listingId": "1150212096",
  "title": "14 Color Ceramic Spoon Rest, Handmade Pottery",
  "price": 18.8,
  "salePrice": 18.8,
  "originalPrice": 47,
  "discountPercent": 60,
  "currency": "USD",
  "ratingValue": 4.8,
  "reviewCount": "3k",
  "imageUrl": "https://i.etsystatic.com/…/il_255x319….jpg",
  "shopName": "ZEEMRusticHomeDecor",
  "shopUrl": "https://www.etsy.com/shop/ZEEMRusticHomeDecor",
  "isAd": true,
  "badges": ["Ad"],
  "url": "https://www.etsy.com/listing/1150212096",
  "shipTo": "US",
  "recordType": "listing"
}
```

***

### Runtime

| Setting | Value |
| --- | --- |
| Default memory | **1024 MB** |
| Min / max memory | 512 / 4096 |
| Proxy | Worker-owned residential egress (`WORKER_PROVIDES_PROXY=1`) |
| Standby | Live View OpenAPI enabled |

***

### FAQ

#### Is this an official Etsy API?

No. This is an **unofficial scraper** for publicly reachable Etsy pages. It is not the [Etsy Open API](https://developers.etsy.com/) and is not affiliated with Etsy.

#### Why scrape Etsy instead of using the Open API?

The Open API requires seller OAuth apps and does not expose the same anonymous SERP / category / featured surfaces. This Actor targets **public search, category, shop, and listing pages** for market research workflows.

#### Can I scrape Etsy by category or shop?

Yes. Use `mode=category` with `categorySlug` (including nested paths like `jewelry/necklaces`), or `mode=shop` with `shopName`. `mode=categories` returns the taxonomy tree.

#### Does ship-to / currency work?

Yes. Set `shipTo` (e.g. `GB`, `DE`, `AU`). The worker applies locale/currency preferences and aligns residential egress to the market. Rows include `currency` when available (or filled from the market default).

#### Why did my free run stop?

Free-plan users get **10 runs** and **200 results/run** — a developer-set policy, not an Apify platform error. Upgrade to a paid Apify plan for unlimited runs (PPE event prices still apply).

#### DataDome / empty results?

Etsy blocks bare HTTP. The worker uses browser automation + residential egress. Hard blocks surface as worker `status=blocked` (HTTP 403), not silent empty success.

#### What is not included?

Login-only member pricing, full review pagination APIs, and official Open API access are out of scope.

***

### Integrations

- [Apify API](https://docs.apify.com/api/v2) / Python / JS client
- Make, Zapier, n8n, and other webhooks via Dataset / run events
- Schedules for recurring price or category monitors

***

### Support

Questions or feature requests? Open an issue on the Actor page or contact the developer via Apify Console.

# Actor input Schema

## `mode` (type: `string`):

search | search\_shops | category | listing | shop | categories | featured

## `shipTo` (type: `string`):

ISO-2 ship-to / regional prefs (currency & language). ROW = fallback USD.

## `query` (type: `string`):

Keyword for mode=search or search\_shops

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

Optional list; first used if query empty

## `categorySlug` (type: `string`):

Top-level or nested path under /c/ e.g. jewelry or jewelry/necklaces

## `listingId` (type: `string`):

Numeric listing id for mode=listing

## `shopName` (type: `string`):

/shop/{name} for mode=shop

## `featuredPath` (type: `string`):

Path for mode=featured e.g. /featured/hub or /r/curated/...

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

Optional Etsy URLs (search, /c/, /listing/, /shop/, /featured/, /r/curated/)

## `order` (type: `string`):

Verified URL codes only: most\_relevant (omit) | price\_asc | price\_desc | date\_desc

## `p` (type: `integer`):

SERP page number (page=N)

## `maxResults` (type: `integer`):

Maximum rows to return (free plan capped at 200)

## `enrichDetails` (type: `boolean`):

Open PDPs for JSON-LD + shipping/sales/images enrichment

## `priceMin` (type: `number`):

Optional min filter (URL min=)

## `priceMax` (type: `number`):

Optional max filter (URL max=)

## `instantDownload` (type: `boolean`):

true/false → instant\_download=; omit for all

## `shipsFrom` (type: `string`):

Ships-from / location facet (locationQuery)

## `readyToShip` (type: `boolean`):

Short EDD window filter (edd=1)

## `starSeller` (type: `boolean`):

is\_star\_seller=true

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

free\_shipping=true

## `language` (type: `string`):

Optional language preference override

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

Optional currency preference override (USD, GBP, …)

## `workerBaseUrl` (type: `string`):

Optional HTTPS allowlisted Cloud Run URL override

## Actor input object example

```json
{
  "mode": "search",
  "shipTo": "US",
  "order": "most_relevant",
  "p": 1,
  "maxResults": 50,
  "enrichDetails": false
}
```

# Actor output Schema

## `results` (type: `string`):

Normalized Etsy listing / shop / category rows from the default dataset.

## `runSummary` (type: `string`):

Structured summary record stored in the default key-value store.

## `inputEcho` (type: `string`):

Normalized input saved at run start.

## `errorSummary` (type: `string`):

Present when a failed run stores structured terminal error information.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("lentic_clockss/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 = {}

# Run the Actor and wait for it to finish
run = client.actor("lentic_clockss/etsy-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 '{}' |
apify call lentic_clockss/etsy-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Etsy Scraper | Listings Shops Categories Prices",
        "description": "Scrape Etsy.com listings, shops & categories — keyword search, nested PLPs, PDP enrich, multi-market ship-to. Extract listingId, prices, ratings, images, badges. Export Excel/CSV/JSON.",
        "version": "0.1",
        "x-build-id": "kPWHWDcGYntxoagqv"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/lentic_clockss~etsy-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-lentic_clockss-etsy-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/lentic_clockss~etsy-scraper/runs": {
            "post": {
                "operationId": "runs-sync-lentic_clockss-etsy-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/lentic_clockss~etsy-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-lentic_clockss-etsy-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "mode": {
                        "title": "Mode",
                        "enum": [
                            "search",
                            "search_shops",
                            "category",
                            "listing",
                            "shop",
                            "categories",
                            "featured"
                        ],
                        "type": "string",
                        "description": "search | search_shops | category | listing | shop | categories | featured",
                        "default": "search"
                    },
                    "shipTo": {
                        "title": "Ship to market",
                        "enum": [
                            "US",
                            "GB",
                            "CA",
                            "AU",
                            "DE",
                            "FR",
                            "IT",
                            "ES",
                            "NL",
                            "IE",
                            "NZ",
                            "JP",
                            "IN",
                            "PH",
                            "MX",
                            "BR",
                            "SE",
                            "DK",
                            "NO",
                            "CH",
                            "AT",
                            "BE",
                            "PL",
                            "KR",
                            "SG",
                            "TW",
                            "HK",
                            "AE",
                            "SA",
                            "TR",
                            "ROW"
                        ],
                        "type": "string",
                        "description": "ISO-2 ship-to / regional prefs (currency & language). ROW = fallback USD.",
                        "default": "US"
                    },
                    "query": {
                        "title": "Search query",
                        "type": "string",
                        "description": "Keyword for mode=search or search_shops"
                    },
                    "searchQueries": {
                        "title": "Search queries",
                        "type": "array",
                        "description": "Optional list; first used if query empty",
                        "items": {
                            "type": "string"
                        }
                    },
                    "categorySlug": {
                        "title": "Category slug",
                        "type": "string",
                        "description": "Top-level or nested path under /c/ e.g. jewelry or jewelry/necklaces"
                    },
                    "listingId": {
                        "title": "Listing ID",
                        "type": "string",
                        "description": "Numeric listing id for mode=listing"
                    },
                    "shopName": {
                        "title": "Shop name",
                        "type": "string",
                        "description": "/shop/{name} for mode=shop"
                    },
                    "featuredPath": {
                        "title": "Featured path",
                        "type": "string",
                        "description": "Path for mode=featured e.g. /featured/hub or /r/curated/..."
                    },
                    "startUrls": {
                        "title": "Start URLs",
                        "type": "array",
                        "description": "Optional Etsy URLs (search, /c/, /listing/, /shop/, /featured/, /r/curated/)",
                        "items": {
                            "type": "string"
                        }
                    },
                    "order": {
                        "title": "Sort order",
                        "enum": [
                            "most_relevant",
                            "price_asc",
                            "price_desc",
                            "date_desc"
                        ],
                        "type": "string",
                        "description": "Verified URL codes only: most_relevant (omit) | price_asc | price_desc | date_desc",
                        "default": "most_relevant"
                    },
                    "p": {
                        "title": "Start page",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "SERP page number (page=N)",
                        "default": 1
                    },
                    "maxResults": {
                        "title": "Max results",
                        "minimum": 1,
                        "maximum": 500,
                        "type": "integer",
                        "description": "Maximum rows to return (free plan capped at 200)",
                        "default": 50
                    },
                    "enrichDetails": {
                        "title": "Enrich listing details",
                        "type": "boolean",
                        "description": "Open PDPs for JSON-LD + shipping/sales/images enrichment",
                        "default": false
                    },
                    "priceMin": {
                        "title": "Min price",
                        "type": "number",
                        "description": "Optional min filter (URL min=)"
                    },
                    "priceMax": {
                        "title": "Max price",
                        "type": "number",
                        "description": "Optional max filter (URL max=)"
                    },
                    "instantDownload": {
                        "title": "Digital downloads",
                        "type": "boolean",
                        "description": "true/false → instant_download=; omit for all"
                    },
                    "shipsFrom": {
                        "title": "Ships from",
                        "type": "string",
                        "description": "Ships-from / location facet (locationQuery)"
                    },
                    "readyToShip": {
                        "title": "Ready to ship",
                        "type": "boolean",
                        "description": "Short EDD window filter (edd=1)"
                    },
                    "starSeller": {
                        "title": "Star Seller only",
                        "type": "boolean",
                        "description": "is_star_seller=true"
                    },
                    "freeShipping": {
                        "title": "Free shipping",
                        "type": "boolean",
                        "description": "free_shipping=true"
                    },
                    "language": {
                        "title": "Language",
                        "type": "string",
                        "description": "Optional language preference override"
                    },
                    "currency": {
                        "title": "Currency",
                        "type": "string",
                        "description": "Optional currency preference override (USD, GBP, …)"
                    },
                    "workerBaseUrl": {
                        "title": "Worker base URL override",
                        "type": "string",
                        "description": "Optional HTTPS allowlisted Cloud Run URL override"
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
