# eBay Product Scraper (`datascrapers/ebay-scraper`) Actor

eBay product dataset from search queries or listing URLs, including prices, condition, seller fields, and optional product-page details.

- **URL**: https://apify.com/datascrapers/ebay-scraper.md
- **Developed by:** [Farhan Ali](https://apify.com/datascrapers) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.97 / 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

**eBay Product Scraper** creates a structured dataset of listings collected from [eBay](https://www.ebay.com) marketplaces. Each dataset item represents one listing and can include identifiers, title, price, currency, condition, buying format, shipping, location, seller feedback, watchers, and bid count, plus optional item-page description, images, and item specifics. Query the source with search, category, or item URLs in `startUrls`, or with `searchQueries` when `startUrls` is empty. Control the result limit with `maxItems`, and retrieve records through the Apify Dataset API or export them as JSON, CSV, Excel, XML, or another supported format.

### Dataset at a glance

| Property | Value |
|---|---|
| Source | eBay marketplaces (ebay.com and regional eBay sites) |
| Record unit | One eBay listing |
| Input methods | Search, category, or item URLs (`startUrls`); `searchQueries` when `startUrls` is empty |
| Main identifiers | `itemId`, `url` |
| Delivery | Apify Dataset and API |
| Export formats | JSON, CSV, Excel, XML, HTML (Apify dataset exports) |
| Update model | Fresh records per Actor run |
| Pricing | $1.00 per 1,000 listings; +$1.50 per 1,000 when `includeProductDetails` is enabled; $0.00005 start charge per run |

### Coverage and available records

The Actor collects listings from public eBay pages using one of two entry points:

- **URL-based**: Pass eBay search URLs, category or browse URLs, or individual item URLs in `startUrls` (for example `https://www.ebay.com/sch/i.html?_nkw=bike`, `https://www.ebay.com/b/Cars-Trucks/6001/bn_1865117`, or `https://www.ebay.com/itm/125459703651`). When `startUrls` is set, constructed search filters are ignored. Start URLs keep the host from the URL.
- **Search-based**: Set `searchQueries` (for example `bike`) only when `startUrls` is empty. Marketplace, category, buying format, condition, sort, location, price range, and sold-listing filters apply to constructed searches.

Record types and limits:

- **Listing-level records** are always collected: `itemId`, title, URL, price, currency, condition, buying format, shipping, item location, image, watchers, bid count, seller, seller feedback, sponsored flag, marketplace, and source metadata.
- **Item-page fields** are conditional: description, images, item specifics, seller, and shipping from the item page are returned only when `includeProductDetails` is enabled.
- **Sold listings** are conditional: set `soldListings` to `true` to collect completed or sold results instead of active listings. This applies to constructed searches only.
- **Result cap**: `maxItems` limits listings collected across all URLs and queries (`0` means unlimited, the default; the console prefill is `10`).

Constructed searches use `EBAY_US` by default or another `EBAY_*` marketplace from the input reference.

Known exclusions: login-only eBay content; historical snapshots; constructed search filters when `startUrls` is set.

### Data dictionary

Field names below match dataset record JSON properties exactly. Fields marked *conditional* appear only when `includeProductDetails` is enabled.

#### Listing-level fields

| Field | Type | Nullable | Description | Example |
|---|---|---:|---|---|
| `itemId` | string | No | eBay item identifier; recommended deduplication key | `125459703651` |
| `title` | string | No | Listing title | `Chopper Lowrider beach Stretch cruiser bike Coaster Brakes Big Fat Bicycle` |
| `url` | string | No | Listing URL; secondary deduplication key | `https://www.ebay.com/itm/125459703651` |
| `price` | number | Yes | Numeric asking or sale price | `664.99` |
| `currency` | string | Yes | ISO currency code for `price` | `USD` |
| `formattedPrice` | string | Yes | Price as displayed on eBay | `$664.99` |
| `condition` | string | Yes | Condition text from the listing | `Brand New` |
| `buyingFormat` | string | Yes | Buying format as shown (for example `Buy It Now`) | `Buy It Now` |
| `shipping` | string | Yes | Shipping snippet from the listing card | `Shipping not specified` |
| `itemLocation` | string | Yes | Item location as shown on the listing | `United States` |
| `imageUrl` | string | Yes | Primary listing image URL | `https://i.ebayimg.com/images/g/dIoAAOSwwihi9Ule/s-l500.webp` |
| `watchers` | number | Yes | Watcher count when eBay shows it | `98` |
| `bidCount` | number | Yes | Auction bid count when eBay shows it | `null` |
| `seller` | string | Yes | Seller username | `reignbike` |
| `sellerFeedbackPercent` | number | Yes | Seller positive-feedback percent | `99.8` |
| `sellerFeedbackCount` | number | Yes | Seller feedback count | `2100` |
| `isSponsored` | boolean | No | Whether the listing is a sponsored result | `false` |
| `marketplace` | string | No | eBay marketplace code for the record | `EBAY_US` |
| `sourceType` | string | Yes | How the listing was reached (for example `search`) | `search` |
| `sourceQuery` | string | Yes | Search term that produced the record | `bike` |

#### Item-page fields (conditional — `includeProductDetails`)

When `includeProductDetails` is enabled, the same listing record can also include description, images, item specifics, seller, and shipping from the item page. These groups are omitted or sparse when the toggle is off or when eBay does not publish the value.

### Example dataset record

Real listing-level record produced with the test input below (`searchQueries: ["bike"]`, `marketplace: "EBAY_US"`). Item-page description, images, and item specifics are not present because this example is the listing card.

```json
{
  "itemId": "125459703651",
  "title": "Chopper Lowrider beach Stretch cruiser bike Coaster Brakes Big Fat Bicycle",
  "url": "https://www.ebay.com/itm/125459703651",
  "price": 664.99,
  "currency": "USD",
  "formattedPrice": "$664.99",
  "condition": "Brand New",
  "buyingFormat": "Buy It Now",
  "shipping": "Shipping not specified",
  "itemLocation": "United States",
  "imageUrl": "https://i.ebayimg.com/images/g/dIoAAOSwwihi9Ule/s-l500.webp",
  "watchers": 98,
  "bidCount": null,
  "seller": "reignbike",
  "sellerFeedbackPercent": 99.8,
  "sellerFeedbackCount": 2100,
  "isSponsored": false,
  "marketplace": "EBAY_US",
  "sourceType": "search",
  "sourceQuery": "bike"
}
```

The record above was produced with this input:

```json
{
  "searchQueries": ["bike"],
  "marketplace": "EBAY_US",
  "category": "0",
  "maxItems": 5,
  "includeProductDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

### Query and input reference

| Input | Type | Required | Default | Accepted values | Description |
|---|---|---:|---|---|---|
| `startUrls` | array (requestListSources) | No\* | — | eBay search, category/browse, or item URLs | URL-based entry point. When set, constructed search filters are ignored |
| `searchQueries` | array (string) | No\* | — | Free-text terms (for example `bike`) | Used only when `startUrls` is empty |
| `marketplace` | string | No | `EBAY_US` | `EBAY_US`, `EBAY_UK`, `EBAY_DE`, `EBAY_AU`, `EBAY_CA`, `EBAY_FR`, `EBAY_IT`, `EBAY_ES`, `EBAY_AT`, `EBAY_CH`, `EBAY_IE`, `EBAY_NL`, `EBAY_BE`, `EBAY_PL`, `EBAY_SG`, `EBAY_HK` | eBay site for constructed searches. Start URLs keep the host from the URL |
| `category` | string | No | `0` | Actor category enum; `0` is All Categories | eBay category ID for constructed searches. Ignored when `startUrls` is set |
| `buyingFormat` | string | No | `all` | `all`, `buy_it_now`, `auction`, `best_offer` | Buying-format filter for constructed searches |
| `condition` | string | No | `any` | `any`, `new`, `open_box`, `certified_refurbished`, `seller_refurbished`, `used`, `for_parts` | Condition filter for constructed searches |
| `sortBy` | string | No | `best_match` | `best_match`, `ending_soonest`, `newly_listed`, `price_shipping_lowest`, `price_shipping_highest`, `nearest` | Sort order for constructed searches |
| `itemLocation` | string | No | `default` | `default`, `domestic`, `worldwide`, `local` | Item-location preference. `local` uses `zipCode` and `distance` |
| `zipCode` | string | No | — | Postal code (for example `10001`, `SW1A 1AA`) | Postal code for nearby / local searches |
| `distance` | integer | No | — | `>= 0` (miles) | Search radius around `zipCode` when `itemLocation` is `local` |
| `minPrice` | number | No | — | `>= 0` | Exclude listings below this price on constructed searches |
| `maxPrice` | number | No | — | `>= 0` | Exclude listings above this price on constructed searches |
| `soldListings` | boolean | No | `false` | `true` / `false` | Collect completed/sold listings instead of active ones (constructed searches only) |
| `maxItems` | integer | No | `0` | `0` or any positive integer | Maximum listings to collect; `0` = unlimited (console prefill `10`) |
| `includeProductDetails` | boolean | No | `false` | `true` / `false` | Add item-page description, images, item specifics, seller, and shipping (charged as `product-details`) |
| `detailConcurrency` | integer | No | `8` | `1`–`15` | Parallel item-page fetches when `includeProductDetails` is enabled |
| `proxyConfiguration` | object | No | Apify proxy, `RESIDENTIAL` group | Apify proxy groups or custom proxies | Residential proxies are recommended |

\* Provide either `startUrls` or `searchQueries`. `searchQueries` is used only when `startUrls` is empty.

Minimal request:

```json
{ "searchQueries": ["bike"], "marketplace": "EBAY_US" }
```

Advanced request (constructed search with filters and item-page fields):

```json
{
  "searchQueries": ["bike"],
  "marketplace": "EBAY_US",
  "category": "177831",
  "buyingFormat": "buy_it_now",
  "condition": "new",
  "sortBy": "price_shipping_lowest",
  "itemLocation": "domestic",
  "minPrice": 100,
  "maxPrice": 800,
  "soldListings": false,
  "maxItems": 50,
  "includeProductDetails": true,
  "detailConcurrency": 8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"]
  }
}
```

### Retrieve the data through the API

The Actor runs on the Apify platform. There is no separate eBay API and no server to host.

1. Start the Actor with a JSON input (console or API).
2. Wait for the run to finish, or use a synchronous endpoint if you want the response inline.
3. Retrieve items from the run's default dataset.
4. Paginate or export the dataset.

Python example:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR-APIFY-TOKEN")

run_input = {
    "searchQueries": ["bike"],
    "marketplace": "EBAY_US",
    "maxItems": 10,
    "includeProductDetails": False,
}

run = client.actor("datascrapers/ebay-scraper").call(run_input=run_input)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["itemId"], item["title"], item["price"])
```

Apify generates ready-to-run Python, JavaScript, and cURL examples on the Actor's [API tab](https://apify.com/datascrapers/ebay-scraper/api). Do not put a real API token in shared code or URLs.

### Data quality and record handling

- **Conditional fields**: description, images, item specifics, and richer seller or shipping values are present only when `includeProductDetails` is enabled. Listings alone return a leaner record.
- **Source values**: prices, condition, buying format, and seller feedback are read from eBay as shown at run time. Unreadable fields are returned as null rather than fabricated.
- **Deduplication**: each run appends fresh records. Deduplicate across runs on `itemId`, or on `url` when `itemId` is missing.
- **Filter scope**: marketplace, category, buying format, condition, sort, location, price range, and `soldListings` apply only to constructed searches. When `startUrls` is set, those filters are ignored.
- **Charges**: `dataset-item` is billed for each listing written to the dataset. `product-details` is billed only when `includeProductDetails` is enabled for that listing.

### Export and pipeline examples

| Destination | Recommended method | Typical use |
|---|---|---|
| PostgreSQL / Supabase | Dataset API poll or webhook consumer | Store listing prices and sellers alongside catalog records |
| Google Sheets | Apify Google Sheets integration | Share price or sold-comp shortlists |
| S3 / cloud storage | Scheduled export via Apify scheduler + integration | Archival of marketplace snapshots |
| Custom warehouse | Dataset API pagination | Load large listing datasets in batches |

### Pricing and cost examples

The Actor uses pay-per-event pricing:

| Event | Trigger | Rate |
|---|---|---|
| `start` | Actor run starts | $0.00005 |
| `dataset-item` | Each listing written to the dataset | $0.001 ($1.00 per 1,000) |
| `product-details` | Each listing opened with `includeProductDetails` | $0.0015 ($1.50 per 1,000) |

Example costs (start charge excluded; add $0.00005 per run):

| Records | Configuration | Estimated base cost |
|---:|---|---:|
| 1,000 | Listing only | $1.00 |
| 10,000 | Listing only | $10.00 |
| 1,000 | Listing + product details | $2.50 |
| 10,000 | Listing + product details | $25.00 |

Compute units consumed by the run are billed by your Apify plan. Estimates depend on the verified pricing model and the options selected for the run.

### Limitations and responsible data use

- The Actor collects publicly accessible data from eBay pages only.
- Field availability depends on what eBay renders at run time; some values can be null or missing, and site changes can alter fields.
- The Actor does not provide historical snapshots unless you store them yourself.
- Constructed search filters are ignored when `startUrls` is set.
- Residential proxies are recommended; coverage may degrade without them.
- You are responsible for compliance with eBay's terms of service, applicable privacy law, and any contractual obligations before using the data.

### Dataset questions

#### What does one dataset item represent?

One eBay listing. Item-page description, images, and item specifics are added to the same record when `includeProductDetails` is enabled, so an enriched listing still produces a single dataset item.

#### Which field should I use as a unique identifier?

`itemId` is the stable eBay item identifier and is the recommended deduplication key. Use `url` as the secondary key when `itemId` is missing.

#### Are fields nullable or conditional?

Yes. Watchers, bid count, shipping, and seller feedback are nullable when eBay does not show them. Description, images, and item specifics exist only when `includeProductDetails` is enabled.

#### Can I retrieve the records as CSV or JSON?

Yes. The dataset can be exported as JSON, CSV, Excel, XML, or HTML from the Apify Console, and queried through the Dataset API.

#### What happens when I set startUrls?

The Actor uses those search, category, or item URLs as the source. `searchQueries` is not used, and constructed search filters (`marketplace`, `category`, `buyingFormat`, `condition`, `sortBy`, `itemLocation`, `zipCode`, `distance`, `minPrice`, `maxPrice`, `soldListings`) are ignored. The URL host is kept as provided.

#### Does the Actor return historical data?

No. Each run captures the state of the pages at run time. To track price or listing changes, schedule repeated runs and store the outputs yourself. Deduplicate later on `itemId` or `url`.

#### What counts as a billable result?

A `start` charge of $0.00005 applies once per run. Every listing written to the dataset charges `dataset-item` at $1.00 per 1,000. Enabling `includeProductDetails` adds `product-details` at $1.50 per 1,000 for each enriched listing.

### Related datasets from Data Scrapers

- **[Amazon Search Scraper](https://apify.com/datascrapers/amazon-scraper)** — Amazon search-result products that can be compared with eBay listings by title or identifier for cross-marketplace pricing.
- **[Etsy Scraper](https://apify.com/datascrapers/etsy-scraper)** — Handmade and vintage product listings for the same catalog or category research as eBay crafts and collectibles.
- **[Gumtree Scraper](https://apify.com/datascrapers/gumtree-scraper)** — UK classified listings that sit alongside eBay UK (`EBAY_UK`) for local marketplace coverage.
- **[Flipkart Product Scraper](https://apify.com/datascrapers/flipkart-scraper)** — Flipkart product records for retail assortment and price comparison outside eBay.
- **[Target.com Product Scraper](https://apify.com/datascrapers/target-scraper)** — Target.com product records for US retail pricing next to eBay US (`EBAY_US`) listings.

### Data Scrapers support

Need an additional field, record type, or export workflow? Contact Data Scrapers at stardustspotlight@gmail.com. Include a sample source URL, required fields, expected record volume, and preferred delivery format.

# Actor input Schema

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

eBay search, category/browse, or item URLs (e.g. https://www.ebay.com/sch/i.html?\_nkw=bike, https://www.ebay.com/b/Cars-Trucks/6001/bn\_1865117, https://www.ebay.com/itm/389640259363). When provided, these URLs are used instead of building a search from queries and filters.

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

Product search terms (e.g. "bike", "iphone 13"). Used only when Start URLs are empty. Combine with category, location, and the filters below.

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

eBay site used for search queries and filters. Start URLs keep the host from the URL.

## `category` (type: `string`):

eBay category applied to constructed searches. Ignored when Start URLs are set.

## `buyingFormat` (type: `string`):

Limit constructed searches to Buy It Now, Auction, or Best Offer listings.

## `condition` (type: `string`):

Item condition filter for constructed searches.

## `sortBy` (type: `string`):

How to sort constructed search results.

## `itemLocation` (type: `string`):

Prefer items located in the selected marketplace country, worldwide, or near a postal code.

## `zipCode` (type: `string`):

Postal code used for nearby / local searches (e.g. "10001", "SW1A 1AA").

## `distance` (type: `integer`):

Search radius around the ZIP / postal code. Used with Item Location = Nearby.

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

Exclude listings below this price on constructed searches.

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

Exclude listings above this price on constructed searches.

## `soldListings` (type: `boolean`):

When enabled, scrape completed/sold listings instead of active ones (constructed searches only).

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

Maximum number of products to scrape across all URLs and queries (0 = unlimited).

## `includeProductDetails` (type: `boolean`):

When enabled, open each item page for description, images, item specifics, seller, and shipping. Charged as the product-details event in addition to each dataset item.

## `detailConcurrency` (type: `integer`):

How many product-detail fetches to run at the same time. Each worker uses its own rotating proxy. Higher is faster.

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

Proxy settings. Apify Residential proxies are recommended for reliable eBay access.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.ebay.com/sch/i.html?_nkw=bike"
    }
  ],
  "searchQueries": [
    "bike"
  ],
  "marketplace": "EBAY_US",
  "category": "0",
  "buyingFormat": "all",
  "condition": "any",
  "sortBy": "best_match",
  "itemLocation": "default",
  "soldListings": false,
  "maxItems": 10,
  "includeProductDetails": false,
  "detailConcurrency": 8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

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

Dataset of scraped eBay products

## `runStats` (type: `string`):

Record count and timestamps for 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 = {
    "startUrls": [
        {
            "url": "https://www.ebay.com/sch/i.html?_nkw=bike"
        }
    ],
    "searchQueries": [
        "bike"
    ],
    "maxItems": 10,
    "detailConcurrency": 8,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("datascrapers/ebay-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 = {
    "startUrls": [{ "url": "https://www.ebay.com/sch/i.html?_nkw=bike" }],
    "searchQueries": ["bike"],
    "maxItems": 10,
    "detailConcurrency": 8,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("datascrapers/ebay-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 '{
  "startUrls": [
    {
      "url": "https://www.ebay.com/sch/i.html?_nkw=bike"
    }
  ],
  "searchQueries": [
    "bike"
  ],
  "maxItems": 10,
  "detailConcurrency": 8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call datascrapers/ebay-scraper --silent --output-dataset

```

## MCP server setup

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