# eBay Marketplace Scraper (`fetch_cat/ebay-marketplace-scraper`) Actor

Export active eBay listings from keywords or public URLs across eight marketplaces, including prices, shipping, auctions, sellers, returns, images, and optional product details.

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

## Pricing

from $0.53 / 1,000 listing extracteds

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/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

## eBay Marketplace Scraper

Export active eBay listings from keyword searches and public search or category URLs. Get normalized prices, shipping, landed cost, seller signals, auction data, images, and optional product details across eight marketplaces.

Use the dataset for price monitoring, product sourcing, resale research, assortment analysis, seller tracking, and auction alerts. No eBay account or developer API key is required.

### Who is it for?

- **Marketplace sellers and resellers** comparing prices, shipping, and competition
- **Retail and brand teams** monitoring listings, discounts, and seller activity
- **Sourcing teams** finding inventory across countries and conditions
- **Researchers and agencies** building repeatable marketplace datasets
- **Auction buyers** tracking newly listed and ending-soon inventory

### Example input

```json
{
  "searchQueries": ["wireless headphones"],
  "marketplace": "US",
  "maxItemsPerQuery": 20,
  "maxPagesPerQuery": 2,
  "sort": "newly_listed",
  "listingType": "all",
  "includeDetails": false
}
```

### Example output

```json
{
  "itemId": "127946512448",
  "title": "Sony WH-1000XM5 Wireless Noise Canceling Headphones - Black",
  "url": "https://www.ebay.com/itm/127946512448",
  "query": "wireless headphones",
  "rank": 1,
  "page": 1,
  "marketplace": "US",
  "price": 225,
  "currency": "USD",
  "shippingCost": 27.4,
  "totalPrice": 252.4,
  "condition": "Open Box",
  "listingType": "best_offer",
  "bestOffer": true,
  "sellerUsername": "authorizedsales",
  "sellerFeedbackPercent": 99.1,
  "imageUrl": "https://i.ebayimg.com/images/g/example/s-l1600.jpg",
  "detailStatus": "not_requested",
  "scrapedAt": "2026-07-10T12:00:00.000Z"
}
```

### What data can you export?

Each row represents one unique active listing.

- **Identity and context:** item ID, title, canonical URL, source URL, query, rank, result page, marketplace, and scrape time
- **Pricing:** numeric and displayed price, currency, original price, discount, coupon, shipping cost, shipping text, and normalized total price
- **Listing signals:** condition, auction/Buy It Now/Best Offer flags, bids, watchers, sold count, time left, and sponsored status
- **Seller and fulfillment:** seller username, feedback percentage/count, item location, ships-from value, return policy, free returns, and free shipping
- **Media:** main image and full image URL list
- **Optional details:** description, item specifics, brand, model, MPN, UPC, EAN, category path, quantity, full gallery, and enrichment status

Fields that eBay does not expose for a listing are returned as `null`; values are not invented.

### Input settings

| Field | Type | Default | Description |
|---|---|---:|---|
| `searchQueries` | string\[] | example query | Keywords to search |
| `startUrls` | URL\[] | empty | Public eBay search or category pages |
| `marketplace` | enum | `US` | `US`, `UK`, `DE`, `FR`, `IT`, `ES`, `CA`, or `AU` |
| `maxItemsPerQuery` | integer | `20` | Unique listings saved per query or URL |
| `maxPagesPerQuery` | integer | `2` | Result pages visited per source, maximum 20 |
| `sort` | enum | `best_match` | Best match, newly listed, ending soonest, price low, or price high |
| `listingType` | enum | `all` | All, auction, Buy It Now, or Best Offer |
| `conditions` | string\[] | empty | Condition shortcuts or numeric eBay condition IDs |
| `minPrice` / `maxPrice` | number | unset | Price range in marketplace currency |
| `freeShippingOnly` | boolean | `false` | Limit keyword searches to free shipping |
| `includeDetails` | boolean | `false` | Visit item pages for product specifics and identifiers |
| `maxRequestRetries` | integer | `2` | New-session retries for blocked pages |
| `proxyConfiguration` | object | residential | Apify Proxy configuration |

Provide at least one search query or start URL. When both are supplied, the Actor processes both. A start URL determines its marketplace from the eBay domain; `marketplace` applies to keyword searches.

### Input recipes

#### Monitor newly listed products in the UK

```json
{
  "searchQueries": ["vintage camera"],
  "marketplace": "UK",
  "sort": "newly_listed",
  "maxItemsPerQuery": 100
}
```

#### Find auctions ending soon

```json
{
  "searchQueries": ["pokemon card psa"],
  "marketplace": "US",
  "listingType": "auction",
  "sort": "ending_soonest",
  "maxItemsPerQuery": 50
}
```

#### Scrape a filtered eBay page

```json
{
  "startUrls": [
    { "url": "https://www.ebay.de/sch/i.html?_nkw=mechanische+tastatur&LH_BIN=1" }
  ],
  "maxItemsPerQuery": 40
}
```

#### Enrich product identifiers

```json
{
  "searchQueries": ["Sony WH-1000XM5"],
  "marketplace": "US",
  "maxItemsPerQuery": 10,
  "includeDetails": true
}
```

### Pricing

This Actor uses pay-per-event pricing. You pay a **$0.005 run start**, then only for records produced.

| Event | Free | Bronze | Silver | Gold | Platinum | Diamond |
|---|---:|---:|---:|---:|---:|---:|
| Listing extracted | $0.0010246 | $0.00089092 | $0.00069492 | $0.00053455 | $0.00035637 | $0.00024946 |
| Successful detail enrichment | $0.00575 | $0.00500 | $0.00390 | $0.00300 | $0.00200 | $0.00140 |

A 100-listing Bronze run without details costs about **$0.094** including the start event. Detail charges apply only when `includeDetails` is enabled and a detail page is successfully enriched. Platform compute and proxy usage may be billed separately according to your Apify plan.

### Tips for reliable runs

- Start with 20 listings and increase the limit after checking the dataset.
- Use keyword mode when you want consistent filters across marketplaces.
- Use start URLs to preserve complex filters selected on eBay.
- Keep detail enrichment off for fast price monitoring; enable it only when identifiers or item specifics are needed.
- For recurring monitoring, schedule the Actor and export results to your database or webhook workflow.
- Keep the default proxy configuration unless you have a tested alternative.

### Legality and responsible use

This Actor extracts publicly visible marketplace information. Scraping public data is generally permitted in many jurisdictions, but laws, eBay terms, and your intended use may differ. Collect only what you need, use reasonable volumes, respect intellectual-property and personal-data rights, and obtain legal advice for regulated or high-risk use cases. Do not use this Actor for account pages, private order data, login-protected information, or prohibited automation.

### Limits and important behavior

- Only public active search/category and item pages are supported. Account, order, message, and private pages are rejected.
- Sold/completed-listing history is outside this Actor's active-marketplace scope.
- eBay may localize shipping and availability according to the request region.
- Some cards do not expose seller, return, watcher, coupon, or shipping details; those fields are `null`.
- Detail pages can be more restrictive than search pages. A detail failure does not remove the base listing; inspect `detailStatus` and `detailError`.
- Results can change between pages while auctions and new listings are updated. Item-ID deduplication prevents duplicate dataset rows.
- Respect eBay's terms, robots policies, applicable law, and personal-data obligations.

### API usage

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

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/ebay-marketplace-scraper').call({
  searchQueries: ['wireless headphones'],
  marketplace: 'US',
  maxItemsPerQuery: 20,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient(token="YOUR_APIFY_TOKEN")
run = client.actor("fetch_cat/ebay-marketplace-scraper").call(run_input={
    "searchQueries": ["wireless headphones"],
    "marketplace": "US",
    "maxItemsPerQuery": 20,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
```

### Use with AI agents through MCP

Connect the Actor to Claude, Cursor, or another MCP client with:

```text
https://mcp.apify.com/?tools=fetch_cat/ebay-marketplace-scraper
```

Example Claude CLI setup:

```bash
claude mcp add apify-ebay "https://mcp.apify.com/?tools=fetch_cat/ebay-marketplace-scraper"
```

Or add a JSON MCP server configuration:

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

Agents can then run product searches and work with the resulting structured dataset.

### Related Actors

- [Google Shopping Results Scraper](https://apify.com/fetch_cat/google-shopping-results-scraper) for cross-market shopping search data
- [AliExpress Products Scraper](https://apify.com/fetch_cat/aliexpress-products-scraper) for sourcing and catalog research
- [Vinted Search Scraper](https://apify.com/fetch_cat/vinted-search-scraper) for resale-market listings

### FAQ

#### Do I need an eBay account or API key?

No. The Actor extracts publicly visible marketplace pages.

#### Can I scrape multiple countries in one run?

Yes. Add start URLs from multiple supported eBay domains. Keyword queries use the single marketplace selected in `marketplace`; run separate inputs when each keyword needs a different marketplace.

#### How are duplicate listings handled?

Rows are deduplicated by eBay item ID across all queries, URLs, and pages in the run. The first occurrence retains its query and rank context.

#### Why is `shippingCost` sometimes null?

A listing can say that shipping is not specified, calculated at checkout, unavailable to the current destination, or visible only on the item page. `shippingText` preserves the displayed message.

#### What happens if eBay serves an error page with HTTP 200?

The Actor validates response size, page markers, and listing cards before parsing. It retries malformed/block pages with a new session and fails clearly after the retry limit instead of returning a misleading successful run with zero items.

#### Does detail enrichment cost extra?

Yes. Each successful detail enrichment has a separate event charge. Base listing extraction is still charged once per saved listing.

### Support

If a run fails or a field is missing, open an issue on the Actor page and include:

- The run ID and complete **input JSON** (remove any secrets)
- A short description of the **expected output**
- A sample of the **actual output** or error message
- One **reproducible public URL** or search query
- The marketplace and whether detail enrichment was enabled

Do not include account credentials, private order data, or other sensitive information.

# Actor input Schema

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

Keywords to search on the selected eBay marketplace. Provide queries, start URLs, or both.

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

Public eBay search or category URLs from a supported marketplace.

## `marketplace` (type: `string`):

Marketplace used for keyword searches. Start URLs are matched to their own domain automatically.

## `maxItemsPerQuery` (type: `integer`):

Stops each query or start URL after this many unique listings.

## `maxPagesPerQuery` (type: `integer`):

Maximum eBay result pages to visit for each source.

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

How keyword search results should be sorted.

## `listingType` (type: `string`):

Limit keyword searches to auctions, Buy It Now, or Best Offer listings.

## `conditions` (type: `array`):

Optional eBay condition filters. Supported shortcuts: new, open\_box, refurbished, used, for\_parts; numeric eBay condition IDs are also accepted.

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

Minimum item price in the selected marketplace currency.

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

Maximum item price in the selected marketplace currency.

## `freeShippingOnly` (type: `boolean`):

Return only listings marked with free shipping for keyword searches.

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

Visit each listing to add item specifics, brand, model, identifiers, gallery images, category path, and return details. This is slower and has a separate per-detail charge.

## `maxRequestRetries` (type: `integer`):

Number of new-session retries for blocked or malformed eBay responses.

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

Residential Apify Proxy is recommended because eBay can return HTTP-200 error pages to cold datacenter sessions.

## Actor input object example

```json
{
  "searchQueries": [
    "wireless headphones"
  ],
  "startUrls": [],
  "marketplace": "US",
  "maxItemsPerQuery": 20,
  "maxPagesPerQuery": 2,
  "sort": "best_match",
  "listingType": "all",
  "conditions": [],
  "freeShippingOnly": false,
  "includeDetails": false,
  "maxRequestRetries": 2,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (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": [
        "wireless headphones"
    ],
    "startUrls": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/ebay-marketplace-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": ["wireless headphones"],
    "startUrls": [],
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/ebay-marketplace-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 '{
  "searchQueries": [
    "wireless headphones"
  ],
  "startUrls": []
}' |
apify call fetch_cat/ebay-marketplace-scraper --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5AgSZ1XsynAR1eXy0/builds/cbQsaa8hyos1xAA5j/openapi.json