# eBay Scraper — Official API: Search, Details & Prices (`commanding_hotdog/ebay-api-scraper`) Actor

Search eBay listings, fetch detailed item info and monitor new arrivals via the official eBay Buy Browse API. No browser, no proxy, no login — just fast, reliable structured data.

- **URL**: https://apify.com/commanding_hotdog/ebay-api-scraper.md
- **Developed by:** [qingwa](https://apify.com/commanding_hotdog) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 80.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

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

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

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

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

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

# README

## eBay Scraper — Official API: Search, Prices, Details & Monitoring

Extract structured eBay listing and item data through the **official eBay Buy Browse API** — no browser automation, no proxy, no login cookies, no risk of getting blocked.

### Why the official API?

- **Stable** — the same API eBay's own apps use; no HTML parsing, no layout-change breakage.
- **Never blocked** — you are an authorised API consumer. No CAPTCHAs, no IP bans.
- **No proxy needed** — the API is open to any server; you pay nothing for traffic.
- **No login / cookies** — just an OAuth 2.0 client-credentials token, refreshed automatically.
- **Clean structured data** — prices, conditions, sellers, shipping, specs, images and more, out of the box.

### Two modes

#### 1. Search mode

Search eBay listings by one or more keyword queries, optionally narrowed by category IDs, GTIN (UPC) or ePID, price range, condition, buying format, seller, free shipping and returns. Results are paginated (200 items per request, up to the eBay 10,000-item query window) and **deduplicated by itemId** across the whole run.

#### 2. Details mode

Fetch the **full item record** for specific items: HTML description (plus a clean plain-text version), all item specifics, brand / GTIN / MPN / ePID, marketing price with discount, estimated sold & available quantity, bid count, return terms and delivery estimates. Accepts v1 item IDs, numeric legacy IDs and any eBay-domain item URL.

#### Monitoring mode (newItemsOnly)

Combine with either mode to output **only item IDs never seen before**. The seen set is persisted across runs in a Key-Value Store, so the actor doubles as a **new-arrival monitor** — ideal for staying on top of fresh listings in a niche.

### Input

| Field | Type | Description |
|---|---|---|
| `mode` | select | `search` or `details` |
| `queries` | stringList | Keywords to search (each executed separately) |
| `categoryIds` | stringList | Narrow to specific eBay category IDs |
| `gtin` | textfield | Search by UPC / GTIN |
| `epid` | textfield | Search by eBay Product ID |
| `sellers` | stringList | Only items from these sellers |
| `itemUrls` | stringList | Item URLs (details mode) |
| `itemIds` | stringList | Item IDs (details mode) |
| `marketplace` | select | 16 eBay marketplaces (US, UK, DE, FR, IT, ES, AT, BE, NL, IE, CH, PL, CA, AU, HK, SG) |
| `minPrice` / `maxPrice` | number | Price range in the marketplace currency |
| `conditions` | multi-select | NEW / USED / UNSPECIFIED |
| `buyingOptions` | multi-select | FIXED_PRICE / AUCTION / BEST_OFFER |
| `freeShippingOnly` | checkbox | Only items with free shipping |
| `returnsAcceptedOnly` | checkbox | Only items accepting returns |
| `searchInDescription` | checkbox | Match query against item description too |
| `sort` | select | bestMatch / priceAsc / priceDesc / newlyListed |
| `maxItems` | number | Total item cap for the run |
| `includeDetails` | checkbox | Also fetch full detail for each search result |
| `newItemsOnly` | checkbox | Monitoring — only output never-seen items |
| `shipToCountry` / `shipToZip` | textfield | Context for calculated-shipping cost & delivery estimates |
| `ebayAppId` / `ebayCertId` | textfield | Your eBay API credentials (or use env vars) |
| `requestConcurrency` | number | Parallel detail requests (default 5) |

### Output

Each dataset record is a flat dictionary with `recordType` = `listing` or `detail`.

**Listing records** include: `itemId`, `legacyItemId`, `title`, `price{value,currency}`, `priceText`, `condition`, `conditionId`, `buyingOptions`, `itemWebUrl`, `imageUrl`, `seller{username, feedbackScore, feedbackPercentage}`, `itemLocation`, `categories`, `shippingOptions`, `itemCreationDate`, `itemEndDate`, `marketplace`, `scrapedAt`.

**Detail records** additionally include: `description` (raw HTML), `descriptionText` (cleaned, capped at 20,000 chars), `additionalImages`, `itemSpecifics`, `brand`, `gtin`, `mpn`, `epid`, `estimatedSoldQuantity`, `estimatedAvailableQuantity`, `bidCount`, `currentBidPrice`, `returnTerms`, `marketingPrice`.

### Pricing

This actor uses **pay-per-event** pricing:

| Event | Price |
|---|---|
| Actor start | $0.00005 |
| Listing record | $0.0025 |
| Detail record | $0.004 |

**The first 20 output records of every run are free.** Billing is batched — you are never charged per-row overhead.

### API quota & your own keys

The eBay Browse API allows **5,000 calls per day per keyset**, shared between search and detail calls. The actor tracks and reports its own call count in the run log.

You can use your **own eBay Developer credentials** via the `ebayAppId` / `ebayCertId` inputs (or the `EBAY_APP_ID` / `EBAY_CERT_ID` environment variables) to get your own independent 5,000/day quota.

### FAQ

**Does this actor give me sold/completed-item history?**
No. eBay's public APIs do not expose completed-sale history. The `estimatedSoldQuantity` field is an eBay-provided demand estimate and is the closest available signal.

**Do I need a proxy or browser?**
No. This is a pure API client — one HTTP request per call, no headless browser, no proxy.

**How many items can I get in one run?**
Up to 10,000 per search query (the eBay query window). Use `maxItems` to cap the run.

**What happens if one item fails?**
It is logged and skipped; the run continues. Failed items are counted in the run summary.

### Example input

```json
{
  "mode": "search",
  "queries": ["wireless headphones", "bluetooth speaker"],
  "marketplace": "EBAY_US",
  "conditions": ["NEW"],
  "buyingOptions": ["FIXED_PRICE"],
  "freeShippingOnly": true,
  "sort": "newlyListed",
  "maxItems": 200,
  "includeDetails": true,
  "requestConcurrency": 5
}
```

### Example details input

```json
{
  "mode": "details",
  "itemUrls": [
    "https://www.ebay.com/itm/386123456789",
    "https://www.ebay.co.uk/itm/sony-headphones/2505883821?var=1"
  ],
  "itemIds": ["v1|123456789012|0"],
  "marketplace": "EBAY_US",
  "shipToCountry": "US",
  "shipToZip": "10001"
}
```

# Actor input Schema

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

search = search listings by keywords/categories; details = fetch full details for specific items.

## `queries` (type: `array`):

Keywords to search for. Each query is executed separately and results are merged (deduplicated by itemId).

## `categoryIds` (type: `array`):

eBay category IDs to narrow the search (comma-separated in the API call). Optional.

## `gtin` (type: `string`):

Search by Global Trade Item Number (UPC only). Optional — at least one of queries / categoryIds / gtin / epid must be provided in search mode.

## `epid` (type: `string`):

Search by eBay Product ID. Optional.

## `sellers` (type: `array`):

Only return items from these seller usernames. Optional.

## `itemUrls` (type: `array`):

eBay item URLs to fetch details for. Supports any eBay domain: /itm/386123456789 or /itm/slug/386123456789?...

## `itemIds` (type: `array`):

eBay item IDs to fetch details for. Supports v1|123|0 format and plain numeric legacy IDs.

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

Which eBay marketplace to query. Determines currency and default item-location filter.

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

Minimum item price in the marketplace currency. Optional.

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

Maximum item price in the marketplace currency. Optional.

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

Filter by item condition. Leave empty for all conditions.

## `buyingOptions` (type: `array`):

Filter by buying format. Leave empty for all formats.

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

Only return items with free shipping (maxDeliveryCost:0).

## `returnsAcceptedOnly` (type: `boolean`):

Only return items where the seller accepts returns.

## `searchInDescription` (type: `boolean`):

Also match the query against the item description, not just the title.

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

Sort order for search results. bestMatch = eBay default relevance ranking.

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

Maximum total number of items to return for this run.

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

For each search result, also call the item-detail API and emit a detail record. Costs more but gives full descriptions and specs.

## `newItemsOnly` (type: `boolean`):

Only output item IDs never seen before. The seen set is persisted in a Key-Value Store across runs, so this turns the actor into a new-arrival monitor.

## `shipToCountry` (type: `string`):

Country code for the shipping-cost calculation context (e.g. US). Required for calculated-shipping items to return delivery cost and estimates.

## `shipToZip` (type: `string`):

ZIP or postal code for the shipping-cost calculation context (e.g. 10001).

## `ebayAppId` (type: `string`):

Your eBay Developer App ID (Client ID) for OAuth 2.0. Falls back to the EBAY_APP_ID environment variable if left empty.

## `ebayCertId` (type: `string`):

Your eBay Developer Cert ID (Client Secret) for OAuth 2.0. Falls back to the EBAY_CERT_ID environment variable if left empty.

## `requestConcurrency` (type: `integer`):

Number of parallel detail requests. Lower is gentler on the API rate limit.

## Actor input object example

```json
{
  "mode": "search",
  "queries": [
    "wireless headphones"
  ],
  "marketplace": "EBAY_US",
  "sort": "bestMatch",
  "maxItems": 100,
  "requestConcurrency": 5
}
```

# Actor output Schema

## `results` (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 = {
    "mode": "search",
    "queries": [
        "wireless headphones"
    ],
    "marketplace": "EBAY_US",
    "sort": "bestMatch",
    "maxItems": 100,
    "requestConcurrency": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("commanding_hotdog/ebay-api-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 = {
    "mode": "search",
    "queries": ["wireless headphones"],
    "marketplace": "EBAY_US",
    "sort": "bestMatch",
    "maxItems": 100,
    "requestConcurrency": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("commanding_hotdog/ebay-api-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 '{
  "mode": "search",
  "queries": [
    "wireless headphones"
  ],
  "marketplace": "EBAY_US",
  "sort": "bestMatch",
  "maxItems": 100,
  "requestConcurrency": 5
}' |
apify call commanding_hotdog/ebay-api-scraper --silent --output-dataset

```

## MCP server setup

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