# eBay Search Scraper (`apt_marble/ebay-search-scraper`) Actor

Search eBay by keyword or paste a search link and get every result as clean data: title, price in the site's own currency, condition, format, shipping, seller and feedback, image and link. Sponsored ads are flagged and organic rank shown apart. Optionally attach full item details.

- **URL**: https://apify.com/apt\_marble/ebay-search-scraper.md
- **Developed by:** [Hamza](https://apify.com/apt_marble) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 search results

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

Learn more: https://docs.apify.com/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 Search Scraper

Search eBay the way a shopper would, and get every result back as clean, structured data. Type one or more keywords — or paste full eBay search links — and receive a row for each listing with its title, price in the site's own currency, condition, buying format, shipping, location, seller and feedback, image and a clean link. Sponsored placements are flagged and the true organic position is reported separately, so you always know which results eBay paid-promoted and which earned their spot. Switch on full item details and every result is enriched with its complete listing record. Built for anyone who needs eBay's search results as data: resellers tracking competitors and price bands, analysts sizing a market, sourcing teams building product lists, and brands watching where their items land in the results.

### What you can do with it

- **Turn a keyword into a dataset** — search "mechanical keyboard" and get back hundreds of live listings with price, condition, seller and rank, ready to filter and pivot.
- **See paid vs. organic placement** — every result carries a sponsored flag and its organic position, so you can measure how many top spots are ads and where the first earned result really sits.
- **Track price bands** — sort by price plus delivery and set a minimum and maximum to map what a product actually sells for right now.
- **Reuse a search you already built on eBay** — paste the eBay search link with all its filters and the actor reads it back; anything you set in the run overrides the link.
- **Monitor a niche on a schedule** — re-run a saved search hourly or daily and compare each fresh dataset against the last.
- **Enrich every result with the full listing** — turn the fast list into a deep dataset with item specifics, all images, exact stock, seller reputation and returns for each result.

### What you get

One row per listing. Abridged sample of a single result:

```json
{
  "query": "laptop",
  "marketplace": "US",
  "itemId": "284267994669",
  "title": "HP ProBook X360 11 G6 Touch Laptop 11.6\" HD Core i3 8GB RAM 128GB SSD Windows 11",
  "url": "https://www.ebay.com/itm/284267994669",
  "imageUrl": "https://i.ebayimg.com/images/g/d-AAAeSwvBFqNd12/s-l500.jpg",
  "sponsored": true,
  "rank": 1,
  "organicRank": null,
  "page": 1,
  "newListing": false,
  "price": { "amount": 169.99, "currency": "USD" },
  "priceTo": null,
  "originalPrice": null,
  "condition": "Good - Refurbished",
  "subtitle": "Good - Refurbished · HP · 128 GB",
  "buyingFormat": "BUY_IT_NOW",
  "bestOffer": false,
  "bids": null,
  "timeLeft": null,
  "shippingCost": 0,
  "freeShipping": true,
  "freeReturns": true,
  "location": "United States",
  "sellerName": "discountcomputerdepot",
  "sellerFeedbackCount": 170600,
  "sellerFeedbackPct": 99.6,
  "leafCategoryId": 177,
  "detailsIncluded": false,
  "scrapedAt": "2026-08-18T12:00:00.000Z"
}
```

With **full item details** switched on, each row keeps everything above and adds the complete listing record — `listingStatus`, the item-page price as `itemPrice`, `itemSpecifics`, all `images`, `quantityAvailable`, `soldCount`, `watcherCount`, `seller`, `itemLocation`, `returnsSummary`, `categoryBreadcrumb`, `epid` and more — and `detailsIncluded` becomes `true`.

### Input reference

| Setting | Type | Default | What it does |
| --- | --- | --- | --- |
| Search terms or search links | list of text | `mechanical keyboard` | One or more keywords, or full eBay search links, mixed in the same list. A pasted link's own filters (site, price range, condition, sort, category) are read from it; anything you set below overrides them. **Required.** |
| Results per search | whole number | `240` | How many results to collect for each search term. eBay serves up to 240 per page and the actor works through the pages automatically until this number is reached or the results run out. Maximum 2,400. |
| Condition | choice | `Any condition` | Limit results to New, Used or Refurbished, or leave on Any. |
| Buying format | choice | `All formats` | Limit results to Buy It Now or Auction, or leave on All. |
| Minimum price | number | — | Only return listings priced at or above this amount, in the selected site's currency. Maximum 1,000,000. |
| Maximum price | number | — | Only return listings priced at or below this amount, in the selected site's currency. Maximum 1,000,000. |
| Free shipping only | true/false | `false` | Return only listings that offer free delivery. |
| Sort results by | choice | `Best Match` | Best Match, Newly Listed, Price + delivery lowest, Price + delivery highest, or Ending Soonest. |
| Category number | text | — | Restrict a keyword search to one eBay category by its numeric id (e.g. 177). Works only together with a search term. |
| Attach full item details | true/false | `false` | Open each result's own listing page and attach the complete record. Slower, and billed separately. |
| eBay site | choice | `United States (ebay.com)` | Which country's eBay site to search: US, UK, Germany, Australia, Canada, France, Italy or Spain. A pasted link keeps its own site. |
| Parallel work | whole number | `4` | How many results to work on at the same time when attaching full item details. Maximum 10. |

### Output fields

| Field | Type | Description |
| --- | --- | --- |
| `query` | text | The search term (or link) this row came from. |
| `marketplace` | text | The eBay site the row was read from. |
| `itemId` | text | eBay's listing number for the item. |
| `title` | text | Listing title as shown to shoppers. |
| `url` | text | Clean link to the listing. |
| `imageUrl` | text | The listing's main image, full size. |
| `sponsored` | true/false | Whether eBay promoted this result as an ad — from eBay's own placement data, not from on-screen labels. |
| `rank` | number | Position in the results exactly as eBay served them, ads included. |
| `organicRank` | number | Position counting only unpaid results; empty on sponsored rows. |
| `page` | number | Which result page the listing was first found on. |
| `newListing` | true/false | Whether eBay marks the listing as newly listed. |
| `price` | object | The price as `{ amount, currency }`, in the site's own currency. Empty amount on some listings that show no fixed price. |
| `priceTo` | number | The upper end when a listing shows a price range. |
| `originalPrice` | number | The struck-through was-price, when a discount is shown. |
| `condition` | text | Item condition, from a known set of condition names. |
| `subtitle` | text | eBay's full subtitle line, including any seller-written extras. |
| `buyingFormat` | text | `BUY_IT_NOW` or `AUCTION`. |
| `bestOffer` | true/false | Whether the listing accepts offers. |
| `bids` | number | Number of bids — auction results only. |
| `timeLeft` | text | eBay's time-left label — auction results only. |
| `shippingCost` | number | Delivery cost shown for the result; `0` when free. |
| `freeShipping` | true/false | Whether delivery is free. |
| `freeReturns` | true/false | Whether the result shows free returns. |
| `location` | text | Where the item is located. |
| `sellerName` | text | The seller's username, when the result shows it. |
| `sellerFeedbackCount` | number | The seller's feedback score, when shown. |
| `sellerFeedbackPct` | number | The seller's positive-feedback percentage, when shown. |
| `leafCategoryId` | number | The category number the result sits in. |
| `detailsIncluded` | true/false | Whether the full item record was attached to this row. |
| `scrapedAt` | text | When the row was collected. |

### Pricing

You pay per result, with no monthly minimum.

| What you are charged for | Price |
| --- | --- |
| Search result — one result added to your dataset | **$0.70 per 1,000** |
| Full item details attached — the complete listing record added to a result | **$1.50 per 1,000** |

The second charge applies only when you switch on full item details, and only for results whose own listing page was successfully read; a result that can be listed but whose page cannot be opened still arrives as a row, and is not charged the second fee.

**Worked example.** A search that collects 1,000 results costs 1,000 × $0.0007 = **$0.70**. Turn on full item details and each result is enriched: add 1,000 × $0.0015 = $1.50, for **$2.20 per 1,000** all-in. A daily run collecting 500 results is about $0.35 per run, roughly $10 a month.

### Limits & what this actor cannot do

- Prices, bids, stock and ranking are a snapshot at the moment of collection and keep changing afterwards; eBay's ranking is not identical from one moment to the next.
- eBay's own result count is an estimate that swings between reads, so it is never returned as a precise total. The actor returns what eBay actually serves and reports distinct listings only — the same item that eBay repeats across nearby pages is returned once.
- There is a practical ceiling of roughly 10,000–24,000 results for any single search-and-filter combination. To go deeper, split a broad search into narrower price bands or categories and run each.
- Seller name and feedback are shown on most results but not all layouts; where a result does not carry them, those fields come back empty rather than guessed.
- The subtitle line is partly seller-written, so `condition` is filled only from a known set of condition names and anything else the seller put there stays in `subtitle`.
- On the two price-plus-delivery sort orders the displayed item price is not strictly increasing, because eBay orders by price including delivery.
- Prices come back in each eBay site's own currency; a figure is never re-labelled into a different currency.
- Speed depends on the size of the job and on eBay's own response times; no fixed throughput is promised.
- eBay's terms govern automated access. You are responsible for using the data lawfully and in line with the source site's terms, and for handling any personal data in line with applicable privacy law.

### FAQ

**Do I need an eBay account?**
No. The actor reads only what eBay shows the public in its search results.

**Does it need my login or password?**
No. There is nothing to connect and nothing to configure — enter a search term and press start.

**Can I paste a search link I already built on eBay?**
Yes. Paste the full eBay search address and the actor reads its site and filters back out. Anything you set in the run overrides the link, and a link left to its own settings is followed as-is.

**How many results can I get per search?**
Up to 2,400 per search in one run, and up to roughly 10,000–24,000 for a single search-and-filter combination overall. Split a broad search into price bands or categories to go wider.

**How is sponsored detection accurate when eBay hides it?**
Sponsored status comes from eBay's own placement data rather than the on-screen "Sponsored" labels, which eBay deliberately scatters onto ordinary results too. Each row reports both its overall rank and its ad-free organic rank.

**Can I schedule it?**
Yes. Schedule it hourly, daily or weekly from the Apify console, and each run writes a fresh dataset you can compare against the last — ideal for tracking price and ranking over time.

**Is the data complete?**
It is complete for everything eBay shows openly in its results. Where a layout omits a field, such as seller feedback on some results, the actor leaves it empty rather than guessing, and it reports distinct listings rather than eBay's shifting estimate of the total.

# Actor input Schema

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

What to search for. Enter one or more keywords (for example "mechanical keyboard"), or paste full eBay search result links — both work, mixed in the same list. When you paste a search link, its own filters (site, price range, condition, sort, category) are read from the link; anything you set below overrides them.

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

How many results to collect for each search term. eBay serves up to 240 results per page and the actor pages through automatically until this number is reached or the results run out.

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

Limit results to a single item condition, or leave on Any.

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

Limit results to Buy It Now listings or auctions, or leave on All.

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

Only return listings priced at or above this amount, in the selected site's currency. Leave empty for no lower bound.

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

Only return listings priced at or below this amount, in the selected site's currency. Leave empty for no upper bound.

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

Return only listings that offer free delivery.

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

The order eBay returns results in. Best Match is eBay's default relevance ranking. Newly Listed shows the freshest listings first. The two price orders rank by price plus delivery, so the displayed item price is not strictly increasing.

## `categoryId` (type: `string`):

Restrict a keyword search to a single eBay category, given as its numeric id (for example 177 for PC Laptops & Netbooks). A category only works together with a search term — it is ignored on searches that have no keyword.

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

Open each result's own listing page and attach the complete record — full title, item specifics, all images, exact stock, seller reputation, returns and more. This reads one extra page per result, so it is slower and is charged separately; leave it off for a fast list of results.

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

Which country's eBay site to search. Prices come back in that site's own currency. A pasted search link keeps its own site regardless of this choice.

## `maxConcurrency` (type: `integer`):

How many results to work on at the same time when attaching full item details. Higher is faster, but eBay serves fewer complete pages when pushed hard. Leave at 4 unless you have a reason.

## Actor input object example

```json
{
  "queries": [
    "mechanical keyboard"
  ],
  "maxItemsPerQuery": 240,
  "condition": "any",
  "buyingFormat": "all",
  "freeShippingOnly": false,
  "sort": "best_match",
  "includeDetails": false,
  "marketplace": "US",
  "maxConcurrency": 4
}
```

# Actor output Schema

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

Every search result this run collected.

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

What this run collected per search, and anything it could not read.

# 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 = {
    "queries": [
        "mechanical keyboard"
    ],
    "maxItemsPerQuery": 240,
    "condition": "any",
    "buyingFormat": "all",
    "sort": "best_match",
    "includeDetails": false,
    "marketplace": "US",
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/ebay-search-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 = {
    "queries": ["mechanical keyboard"],
    "maxItemsPerQuery": 240,
    "condition": "any",
    "buyingFormat": "all",
    "sort": "best_match",
    "includeDetails": False,
    "marketplace": "US",
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/ebay-search-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 '{
  "queries": [
    "mechanical keyboard"
  ],
  "maxItemsPerQuery": 240,
  "condition": "any",
  "buyingFormat": "all",
  "sort": "best_match",
  "includeDetails": false,
  "marketplace": "US",
  "maxConcurrency": 4
}' |
apify call apt_marble/ebay-search-scraper --silent --output-dataset

```

## MCP server setup

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