# eBay Auction Monitor (`apt_marble/ebay-auction-monitor`) Actor

Track live eBay auctions in one run: current bid, number of bids, reserve flag and a clean end time for every listing. Watch a fixed list of auctions or find them by keyword, and keep only the ones ending soon. Schedule it to build a bidding time series.

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

## Pricing

$2.00 / 1,000 auction snapshots

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 Auction Monitor

Take a clean, timestamped reading of any live eBay auction. For every listing you get the current bid, how many bids it has taken, whether a reserve is set, the exact time it ends and how much time is left — plus the seller, condition and item location. Feed it a fixed list of auctions, or let it find auctions by keyword, and run it on a schedule to build a bid-by-bid history over time.

Each run is a single snapshot. Run it once for a one-off look, or schedule it every few minutes near closing time to watch bids climb.

### What you can do with it

- **Watch specific auctions** you care about and record how the bidding moves.
- **Discover auctions by keyword** — for example "pokemon card" or "vintage rolex" — ordered by which end first.
- **Focus on auctions ending soon** by keeping only listings that close within a chosen number of hours.
- **Build a price-over-time history** by scheduling repeat runs and comparing snapshots.
- **Spot reserve and Buy It Now details** so you know when a listing can be bought outright.
- **Track seller reputation** on each auction alongside the bidding data.

### What you get

One record per auction. An abridged example:

```
{
  "itemId": "137607207259",
  "title": "Blaziken Emerald Reverse Holo Card 1/106",
  "marketplace": "US",
  "listingStatus": "ACTIVE",
  "buyingFormat": "auction",
  "currentBid": { "amount": 202.5, "currency": "USD" },
  "bidCount": 8,
  "hasReservePrice": false,
  "reserveMet": null,
  "buyItNowPrice": null,
  "startDate": "2026-08-11T00:47:28.000Z",
  "endDate": "2026-08-18T00:47:28.000Z",
  "timeRemainingSeconds": 2848,
  "watchers": 36,
  "condition": "Ungraded - Near mint or better",
  "seller": { "username": "shadowwizardtcg", "feedbackScore": 345, "feedbackPct": 100 },
  "itemLocation": "San Antonio, TX, United States",
  "imageUrl": "https://i.ebayimg.com/images/g/VLEAAeSwTy5qYTXi/s-l1600.webp",
  "url": "https://www.ebay.com/itm/137607207259",
  "source": "auctions",
  "capturedAt": "2026-08-18T00:00:00.000Z"
}
```

### Input reference

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| Auction links or item numbers | list of text | — | Auctions you already want to watch. Full eBay links and bare item numbers both work, mixed together. Up to 5,000 per run. |
| Discover auctions by keyword | list of text | — | Keywords to find live auctions with. Each keyword is searched for auctions ordered by which end first. |
| Only auctions ending within (hours) | whole number | empty | For keyword discovery only: keep just the auctions ending within this many hours. Leave empty to keep every auction a keyword finds. Maximum 720. |
| Max auctions per keyword | whole number | `60` | How many auctions to take from each keyword search. Maximum 240. |
| eBay site | select | `US` | Which country's eBay site to read auctions on. |
| Parallel auctions | whole number | `4` | How many auctions to work on at the same time. Higher is faster, but eBay serves fewer complete pages when pushed hard. Maximum 10. |

At least one of the two auction inputs is required — a fixed list, keywords, or both.

### Output fields

| Field | Description |
| --- | --- |
| `itemId` | eBay item number. |
| `title` | Listing title. |
| `marketplace` | The eBay site the auction was read on. |
| `listingStatus` | `ACTIVE`, `ENDED` or `SOLD`. |
| `buyingFormat` | `auction`, `auction-with-bin` (auction that also offers Buy It Now) or `buy-it-now`. |
| `currentBid` | Current high bid `{ amount, currency }`, or empty on non-auctions. |
| `bidCount` | Number of bids placed, or empty when the listing is not an auction. |
| `hasReservePrice` | Whether the auction has a reserve. |
| `reserveMet` | Whether eBay has published that the reserve is met (empty when eBay does not show it). |
| `buyItNowPrice` | The Buy It Now price `{ amount, currency }` when the listing offers one. |
| `startDate` / `endDate` | When the listing started and ends, as full timestamps. |
| `timeRemainingSeconds` | Seconds left until the auction ends, measured at the moment of collection. |
| `watchers` | How many people are watching the listing, when eBay shows it. |
| `condition` | Item condition. |
| `seller` | `{ username, feedbackScore, feedbackPct }`. |
| `itemLocation` | Where the item is located. |
| `imageUrl` | Main listing image. |
| `url` | Canonical eBay listing link. |
| `source` | `auctions` for a listing you supplied, `discovery` for one found by keyword. |
| `discoveryQuery` | The keyword that found the auction, when it was discovered. |
| `capturedAt` | When this reading was taken. |

### Pricing

You pay per auction captured — one charge for each result in the dataset, and nothing else.

- **Auction snapshot** — $0.002 per auction (that is $2.00 per 1,000).

Worked example: watching 250 auctions costs about **$0.50**; a keyword sweep that reads 1,000 auctions costs about **$2.00**. Apify platform usage is billed separately by Apify.

### Limits & what this actor cannot do

- Bids, prices, watchers and stock are a reading taken at one moment and keep changing after collection — schedule repeat runs if you need to follow them.
- Bid count, current bid and reserve status come from the auction listing itself. On listings that are not auctions those bidding columns are simply empty, and the Buy It Now price is filled in instead.
- Auctions that have been removed, ended or never existed are reported as unavailable rather than returned as an error; ended and sold auctions still come back with a full row so you keep the final numbers.
- The "ending within" filter for keyword discovery uses eBay's own remaining-time label on each search result; it is accurate to the minute eBay shows, not to the second.
- Keyword discovery reads eBay's auction search results, whose ordering and totals eBay itself varies between reads; the actor returns the auctions eBay actually serves.
- Delivery cost and shipping eligibility are not reported, because eBay shows those differently depending on where a page is read from — they would not be reliable for you.
- Speed depends on the size of the job and on eBay's own response times; no fixed rate is promised.
- eBay's terms govern automated access. You are responsible for using the data lawfully and in line with eBay's terms, and for handling any personal data in line with applicable privacy law.

### FAQ

**Do I need an eBay account?** No. It reads publicly visible auction pages — no account required.

**Does it need my login or password?** No. No login of any kind is used.

**Can I schedule it?** Yes. Each run is one snapshot, so scheduling it (for example every few minutes near an auction's close) builds a bid-by-bid history.

**Can I just give it keywords instead of links?** Yes. Put keywords in `discoveryQueries` and the actor finds live auctions for you, newest-ending first. You can also combine keywords with a fixed list of auctions.

**Why is `bidCount` empty on some rows?** That listing is not an auction (it is a fixed-price Buy It Now item). Its price appears in `buyItNowPrice` instead.

**Is the data complete?** It reflects what eBay shows at the moment of collection. Values change afterwards, and removed listings are reported as unavailable, so treat each run as a point-in-time snapshot.

# Actor input Schema

## `auctions` (type: `array`):

Auctions you already want to watch. Paste full eBay item links or bare item numbers — both work, mixed in the same list. Leave empty if you only want to discover auctions by keyword below. Up to 5,000 auctions per run.

## `discoveryQueries` (type: `array`):

Keywords to find live auctions with, for example "pokemon card" or "vintage rolex". Each keyword is searched for auctions ordered by which end first. Use this instead of, or together with, a fixed list above.

## `endingWithinHours` (type: `integer`):

For keyword discovery only: keep just the auctions ending within this many hours, so a run stays focused on soon-to-close listings. Leave empty to keep every auction a keyword finds. Ignored for auctions you listed yourself.

## `maxDiscoveredPerQuery` (type: `integer`):

How many auctions to take from each keyword search before reading them. Higher finds more but costs more per run.

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

Which country's eBay site to read auctions on. Bids and prices come back in the seller's own currency regardless of the site chosen.

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

How many auctions to work on at the same time. 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
{
  "auctions": [
    "https://www.ebay.com/itm/137607207259"
  ],
  "discoveryQueries": [
    "pokemon card"
  ],
  "maxDiscoveredPerQuery": 60,
  "marketplace": "US",
  "maxConcurrency": 4
}
```

# Actor output Schema

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

Every auction snapshot this run captured.

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

What this run captured, 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 = {
    "auctions": [
        "https://www.ebay.com/itm/137607207259"
    ],
    "discoveryQueries": [
        "pokemon card"
    ],
    "maxDiscoveredPerQuery": 60,
    "marketplace": "US",
    "maxConcurrency": 4
};

// Run the Actor and wait for it to finish
const run = await client.actor("apt_marble/ebay-auction-monitor").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 = {
    "auctions": ["https://www.ebay.com/itm/137607207259"],
    "discoveryQueries": ["pokemon card"],
    "maxDiscoveredPerQuery": 60,
    "marketplace": "US",
    "maxConcurrency": 4,
}

# Run the Actor and wait for it to finish
run = client.actor("apt_marble/ebay-auction-monitor").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 '{
  "auctions": [
    "https://www.ebay.com/itm/137607207259"
  ],
  "discoveryQueries": [
    "pokemon card"
  ],
  "maxDiscoveredPerQuery": 60,
  "marketplace": "US",
  "maxConcurrency": 4
}' |
apify call apt_marble/ebay-auction-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,apt_marble/ebay-auction-monitor"
        }
    }
}

```

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/4SamrcYlPgQaV1M50/builds/P6gC9sBiQ9ks5cBzT/openapi.json