# eBay Scraper - Prices, Sold Intelligence & Auction Data (`harvestlab/ebay-scraper`) Actor The only eBay scraper with cross-run sold-price trend tracking. Covers 13 country domains, auction + BIN modes, sold-listings intelligence (recommended list price, p10-p90 band, velocity), AI analysis, 25+ fields. Pay-per-event. - **URL**: https://apify.com/harvestlab/ebay-scraper.md - **Developed by:** [Nick](https://apify.com/harvestlab) (community) - **Categories:** E-commerce, AI, Lead generation - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Scraper - Products, Prices & Sold Intelligence Scrape eBay product listings with prices, shipping, seller ratings, condition, and bid counts. Search any eBay domain (US, UK, DE, AU, FR, IT, and 7 more). **v1.9: sold-listings intelligence mode** — flip `soldOnly=true` and get a reseller-grade pricing summary with recommended list price, p10-p90 price band, median days-to-sell, market velocity, and confidence score. **NEW v2.0: cross-run sold-listings trend** — the summary now carries a `sold_listings_trend` block with 7d/30d price deltas, velocity / volume deltas, and direction from persisted history. Auction + Buy It Now + optional AI market analysis. ### What's new in v2.0 — Sold-Listings Trend (Cross-Run Surveillance) Turn the one-shot reseller scrape into a market-watch service. Run the same `soldOnly=true` search on a schedule (daily, weekly) and every summary item now carries a `sold_listings_trend` block populated from prior runs: | Trend field | What it tells you | |---|---| | `has_history` | Bool — `false` on the first run (seeds the store), `true` thereafter. | | `price_delta_7d_pct` / `price_delta_30d_pct` | Median-price % change vs the snapshot closest to 7 / 30 days ago. | | `recommended_delta_7d_pct` / `recommended_delta_30d_pct` | Same, but over `recommended_list_price` — the headline reseller number. | | `volume_delta_pct` | % change in `n_sold_listings` vs the previous snapshot (demand-side signal). | | `velocity_delta` | e.g. `"steady -> hot"` — categorical market-velocity transition. | | `velocity_rank_delta` | Signed int over `cold < slow < steady < hot` (+1 = one bucket hotter). | | `direction` | `up` / `down` / `flat` / `new` — short-horizon tick relative to the last snapshot. | | `sample_count_history` | How many prior snapshots informed the trend (capped at 90 = ~3 months of daily runs). | | `first_seen_at` / `previous_snapshot_at` | Audit trail — earliest stored run + most recent. | | `previous_recommended_list_price` / `previous_median_price` | Prior-run anchor values so consumers can recompute custom deltas. | **How it works**: each run persists the summary into a **named** Apify key-value store (`ebay-sold-history`) keyed by `(searchQuery, domain)` slug. The store is FIFO-capped at 90 snapshots per slot so it stays bounded. Trend fields are computed against the stored history — no extra HTTP, no extra AI call. Pattern matches `booking-scraper/_rate_history.py` (rate-trend) and `amazon-scraper` (BSR-trend). **Billing**: trend detection bills `sold-trend-detected @ $0.03` once per run — **only when prior history exists**. First runs seed the store and are free. A daily watch on 10 SKUs at ~$0.03/trend-snapshot = ~$9/month vs Terapeak's $20/mo flat, and you own the raw time-series. ### What's new in v1.9 — Sold-Listings Intelligence Mode Set `soldOnly: true` and the scraper flips to eBay's `LH_Sold=1&LH_Complete=1` filter (completed sales, ~90 day window). In addition to the individual sold-listing records, the run emits a single `sold_listings_summary` item with everything a reseller or arbitrage operator needs to price a SKU: | Summary field | What it tells you | |---|---| | `recommended_list_price` | p60 of sold prices when n>=20, else median. The "asking price that still sells reliably". | | `p10_p90_range` | p10 / p25 / p75 / p90 price band — the realistic spread across the market. | | `median_price`, `mean_price` | Classic central-tendency anchors. | | `median_days_to_sell` / `p90_days_to_sell` | How fresh / how slow the market signal is. | | `market_velocity` | `hot` (1+/day), `steady` (~2-7/week), `slow` (~1-2/week), `cold` (<1/week). | | `confidence_score` | 0-1 score blending sample size (50%), price dispersion (30%), sold-date parse coverage (20%). | | `n_sold_listings`, `currency`, `lookback_days`, `methodology` | Transparent metadata so downstream consumers can audit / override. | Pricing: sold-listings bill at `$0.005/listing` (vs. $0.003 for live listings) and the summary bills once at `$0.10`. A 100-sold run costs $0.50 + $0.10 = **$0.60** end-to-end — roughly 5x cheaper than competitor premium sold-intelligence offerings at ~$25/1000 results. ### Features - **Sold-listings intelligence mode** (v1.9) — completed-sale aggregation with recommended list price, p10-p90 band, velocity, and confidence score - Search any eBay marketplace by keyword (13 supported country domains) - Extract 25+ data points per listing: title, price, strikethrough MSRP (`list_price`), currency, shipping, condition, seller + feedback, bids, time-left, sold count (integer), sold date (ISO-8601 when in sold mode), sponsored flag, best-offer flag, images, location - Filter by listing type (auction, Buy It Now, or all) - Filter by item condition (new, used, refurbished, open box) - Sort by best match, price, newest listed, or ending soonest - Set minimum and maximum price filters - Paginate through search results automatically (up to 200 products) - Scrape direct eBay product URLs for detail pages - AI-powered market analysis with pricing insights, value picks, and buying recommendations - Supports 5 LLM providers: OpenRouter (recommended — 300+ models), Anthropic (Claude), Google AI (Gemini), OpenAI (GPT), and Ollama (self-hosted) - Pay-per-event pricing: only pay for what you scrape ### Use Cases - **Resellers & Arbitrage**: Compare eBay prices to other platforms for profitable flips - **Price Monitoring**: Track prices for specific products over time - **Market Research**: Analyze pricing trends, demand, and competition for product categories - **Competitive Analysis**: Monitor competitor pricing and seller strategies - **Auction Intelligence**: Track active auctions, bid counts, and time remaining - **E-commerce Sourcing**: Find wholesale or bulk deals on eBay - **Vintage & Collectibles**: Monitor rare item prices and auction activity ### Data Extracted #### Search Results | Field | Description | |-------|-------------| | `title` | Product listing title | | `url` | Direct link to the eBay listing | | `price` | Current numeric price value | | `price_text` | Current price as displayed (e.g., "$29.99") | | `currency` | ISO 4217 currency code (e.g. `USD`, `GBP`, `EUR`) — resolved from price symbol when unambiguous, else from domain (Cycle 50). | | `list_price` | Strikethrough / MSRP numeric price if the listing shows a discount, else `null`. Useful for discount-% and margin analysis. (v1.8 / Cycle 73) | | `list_price_text` | Strikethrough price as displayed (e.g. `"$299.99"`) — only populated when the listing is discounted. (v1.8) | | `shipping_cost` | Shipping cost (0.0 for free shipping, null if unknown) | | `shipping_text` | Shipping info as displayed | | `free_shipping` | Bool convenience flag derived from `shipping_cost == 0` or localized "free shipping" markers. | | `condition` | Item condition (New, Used, Pre-Owned, Refurbished, etc.) | | `seller` | Combined human-readable seller string, e.g. `"logitech 99.6% positive (20.7K)"`. Populated for Buy It Now listings in search results, OR for any listing when `fetchDetails=true` is enabled (eBay does not render seller info in auction search cards). | | `seller_username` | Bare seller username, e.g. `"logitech"`, `"jdw.55"` — populated whenever `seller` is populated. | | `seller_feedback_percentage` | Seller feedback percentage as float, e.g. `99.6`. | | `seller_feedback_count` | Seller feedback count as int, e.g. `20700` (parsed from `"(20.7K)"`). | | `bids` | Number of bids (auction items only) | | `time_left` | Time remaining for auctions | | `listing_type` | `auction`, `buy_it_now`, or `buy_it_now_or_best_offer` | | `best_offer` | Bool convenience flag — `true` when seller accepts offers (equivalent to `listing_type == "buy_it_now_or_best_offer"`). (v1.8) | | `is_sponsored` | Bool — `true` when the card is a promoted/sponsored listing. Filter these out for organic price-distribution analysis. (v1.8) | | `image_url` | Product image URL | | `sold_info` | Raw sold/watching text as displayed (e.g., "184+ sold", "5 watching"). | | `sold_count` | Integer sold count parsed from `sold_info`. `null` when the card shows watchers only or no sold-badge. Handles `K`/`M` suffixes (`"2.1K+ sold"` → `2100`). (v1.8) | | `sold_date` | ISO-8601 date (YYYY-MM-DD) when the listing sold — populated only in `soldOnly` mode. (v1.9) | | `sold_date_text` | Raw sold-date caption as displayed ("Sold Mar 15, 2026" / "Verkauft am 15. Mär 2026"). (v1.9) | | `is_sold` | Bool — `true` when the listing came from `soldOnly` mode (completed sale). (v1.9) | | `location` | Seller location | | `domain` | eBay domain used for scraping | | `search_query` | Original search term | | `scraped_at` | ISO 8601 timestamp of extraction | #### Sample Output ```json { "title": "Pokemon TCG Scarlet & Violet Booster Box - 36 Packs - Sealed", "url": "https://www.ebay.com/itm/295854732101", "price": 129.99, "price_text": "$129.99", "currency": "USD", "list_price": 159.99, "list_price_text": "$159.99", "shipping_cost": 0.0, "shipping_text": "Free shipping", "free_shipping": true, "condition": "New", "seller": "pokemon_central 99.8% positive (14.2K)", "seller_username": "pokemon_central", "seller_feedback_percentage": 99.8, "seller_feedback_count": 14200, "bids": null, "time_left": null, "listing_type": "buy_it_now", "best_offer": false, "is_sponsored": false, "image_url": "https://i.ebayimg.com/images/g/abc123/s-l1600.webp", "sold_info": "184+ sold", "sold_count": 184, "location": "Los Angeles, CA", "domain": "ebay.com", "search_query": "pokemon cards", "scraped_at": "2026-04-18T10:15:00Z" } ```` ### Input Configuration #### Search Parameters - `searchQuery` — Keyword to search for on eBay (e.g., "laptop", "iPhone 15", "vintage watch"). The actor also accepts the aliases `query`, `q`, `search`, `keyword`, and `searchTerm` (Cycle 65 v1.3) so existing workflows that use different naming conventions work without changes. - `productUrls` — List of direct eBay product URLs to scrape (alternative to search) - `ebayDomain` — eBay country domain. Options: `ebay.com` (US), `ebay.co.uk` (UK), `ebay.de` (Germany), `ebay.fr` (France), `ebay.it` (Italy), `ebay.es` (Spain), `ebay.com.au` (Australia), `ebay.ca` (Canada), `ebay.nl` (Netherlands), `ebay.be` (Belgium), `ebay.at` (Austria), `ebay.ch` (Switzerland), `ebay.ie` (Ireland) - `listingType` — Filter by listing type: `all`, `auction`, or `buy_it_now` - `sortBy` — Sort results: `best_match`, `price_low`, `price_high`, `ending_soonest`, `newly_listed` - `itemCondition` — Filter by condition: `any`, `new`, `open_box`, `refurbished`, `used` - `minPrice` — Minimum price filter - `maxPrice` — Maximum price filter - `maxProducts` — Maximum number of products to scrape (1-200, default 50) #### AI Analysis Settings - `enableAiAnalysis` — Enable AI-powered market pricing analysis (default: false) - `llmProvider` — LLM provider: `openrouter` (default), `anthropic`, `google`, `openai`, or `ollama` - `openrouterApiKey` — OpenRouter API key (get one at [openrouter.ai](https://openrouter.ai/keys)) - `anthropicApiKey` — Anthropic API key (get one at [console.anthropic.com](https://console.anthropic.com/)) - `googleApiKey` — Google AI API key (get one at [aistudio.google.com/app/apikey](https://aistudio.google.com/app/apikey)) - `openaiApiKey` — OpenAI API key (get one at [platform.openai.com](https://platform.openai.com/api-keys)) - `llmModel` — Custom LLM model (defaults: `google/gemini-2.0-flash-001` for OpenRouter, `claude-sonnet-4-20250514` for Anthropic, Gemini for Google AI, GPT-4o Mini for OpenAI, Llama 3.1 for Ollama) #### Proxy Settings - `proxyConfiguration` — Apify Proxy settings. Works without proxy for most searches. Use residential proxy if you experience blocking. ### AI Market Analysis When enabled, the AI analyzes all scraped products and provides: - **Market Overview**: Average price, median price, price range, dominant condition, auction vs BIN ratio - **Price Analysis**: Budget, mid-range, and premium price brackets with best value picks - **Seller Landscape**: Patterns in seller behavior, trusted sellers with high feedback - **Buying Recommendations**: Best time to buy, negotiation tips for Best Offer listings, red flags, top picks - **Market Trends**: Demand indicators from bids and sold counts, condition premium analysis, shipping patterns ### Example Usage #### Basic search ```json { "searchQuery": "mechanical keyboard", "maxProducts": 20 } ``` #### Filtered search with price range ```json { "searchQuery": "vintage Rolex watch", "ebayDomain": "ebay.com", "listingType": "auction", "sortBy": "ending_soonest", "minPrice": 500, "maxPrice": 5000, "maxProducts": 50 } ``` #### Used electronics on eBay UK ```json { "searchQuery": "MacBook Pro", "ebayDomain": "ebay.co.uk", "itemCondition": "used", "sortBy": "price_low", "maxProducts": 30 } ``` #### With AI market analysis ```json { "searchQuery": "Nintendo Switch OLED", "maxProducts": 50, "enableAiAnalysis": true, "llmProvider": "openrouter", "openrouterApiKey": "sk-or-..." } ``` #### Direct product URLs ```json { "productUrls": [ "https://www.ebay.com/itm/123456789", "https://www.ebay.com/itm/987654321" ] } ``` #### Sold-listings intelligence mode (v1.9) ```json { "searchQuery": "pokemon booster box", "ebayDomain": "ebay.com", "soldOnly": true, "maxProducts": 100, "soldDateLookback": 90 } ``` The run returns up to 100 completed-sale listings AND a single `sold_listings_summary` item: ```json { "type": "sold_listings_summary", "search_query": "pokemon booster box", "domain": "ebay.com", "lookback_days": 90, "n_sold_listings": 100, "currency": "USD", "recommended_list_price": 129.95, "median_price": 119.50, "mean_price": 128.30, "p10_p90_range": {"p10": 65.00, "p25": 89.99, "p75": 149.99, "p90": 199.00}, "price_range": {"min": 24.99, "max": 349.00}, "median_days_to_sell": 18, "p90_days_to_sell": 62, "market_velocity": "hot", "confidence_score": 0.87, "date_coverage_ratio": 0.92, "generated_at": "2026-04-22T23:00:00Z", "methodology": "Sold-listings aggregation over eBay's LH_Sold=1&LH_Complete=1 completed-sale filter..." } ``` ### Pricing | Event | Price per event | Description | |-------|----------------|-------------| | `product-scraped` | $0.003 | Charged per live product listing extracted (default mode) | | `sold-listing-scraped` | $0.005 | Charged per completed-sale listing in `soldOnly` mode (v1.9) | | `sold-summary-generated` | $0.10 | Charged once per run when the `sold_listings_summary` is emitted (v1.9) | | `sold-trend-detected` | $0.03 | Charged once per run when `sold_listings_trend` is populated from prior history (v2.0). First run seeds the store for free; charges start on the 2nd and later runs. | | `ai-analysis-completed` | $0.05 | Charged per AI market analysis report | A 100-sold-listings run with the summary costs $0.50 + $0.10 = $0.60 (first run) or $0.63 (from the 2nd run onward, trend included). Compare to competitor sold-intelligence offerings at ~$25/1000 results + Terapeak's $20/mo subscription — roughly 5x cheaper per aggregation, and you own the raw time-series. ### Technical Details - Uses Playwright headless Chromium to render eBay's JavaScript-heavy search pages - Automatic retry with exponential backoff on rate limits (429) and access denied (403) - Polite crawling with 1-2.5 second delays between requests - Supports pagination across multiple search result pages - **Cross-page deduplication** — eBay's search pagination can surface the same listing on consecutive pages (especially with `newly_listed` / `ending_soonest` sorts). The scraper tracks a `seen_product_urls` set across pages and skips duplicates, so `maxProducts=50` returns 50 unique listings rather than 50 raw slots. - Multiple parsing strategies to handle eBay's evolving DOM structure - Clean URLs with tracking parameters stripped - Requires 4096 MB memory (Playwright + Chromium) ### Supported eBay Domains | Domain | Country | Currency | |--------|---------|----------| | `ebay.com` | United States | USD | | `ebay.co.uk` | United Kingdom | GBP | | `ebay.de` | Germany | EUR | | `ebay.fr` | France | EUR | | `ebay.it` | Italy | EUR | | `ebay.es` | Spain | EUR | | `ebay.com.au` | Australia | AUD | | `ebay.ca` | Canada | CAD | | `ebay.nl` | Netherlands | EUR | | `ebay.at` | Austria | EUR | | `ebay.ch` | Switzerland | CHF | | `ebay.ie` | Ireland | EUR | | `ebay.pl` | Poland | PLN | Each domain returns results in the local currency and language. The scraper automatically adapts to the search result format of each country site. ### Output Example ```json { "title": "Sony WH-1000XM5 Wireless Noise Cancelling Headphones - Black", "url": "https://www.ebay.com/itm/295463812345", "price": 248.00, "price_text": "$248.00", "currency": "USD", "list_price": 399.99, "list_price_text": "$399.99", "shipping_cost": 0.0, "shipping_text": "Free shipping", "free_shipping": true, "condition": "Brand New", "seller": "top_electronics 99.2% positive (12.3K)", "seller_username": "top_electronics", "seller_feedback_percentage": 99.2, "seller_feedback_count": 12345, "bids": null, "time_left": null, "listing_type": "buy_it_now", "best_offer": false, "is_sponsored": false, "image_url": "https://i.ebayimg.com/images/g/.../s-l225.jpg", "sold_info": "184+ sold", "sold_count": 184, "location": "New Jersey, United States", "domain": "ebay.com", "search_query": "Sony WH-1000XM5", "scraped_at": "2026-04-18T10:30:00Z" } ``` ### Integration & Export Data can be exported in multiple formats directly from the Apify platform: - **JSON** — structured data ready for APIs and applications - **CSV** — import into spreadsheets, Google Sheets, or databases - **Excel** — ready for business analysis and reporting - **XML** — compatible with data pipelines and ETL tools You can also integrate with 2,000+ apps via Apify's built-in integrations including Google Sheets, Slack, Zapier, Make (Integromat), webhooks, and Amazon S3. ### Frequently Asked Questions **Does this scraper work without proxy?** Yes, eBay works with datacenter proxies for most searches. Residential proxy is only needed if you experience blocking on high-volume scrapes. **How many products can I scrape per run?** Up to 200 products per run. For larger datasets, run the actor multiple times with different search queries or pagination offsets. **Can I scrape specific product detail pages?** Yes, provide direct eBay product URLs via the `productUrls` input field instead of using keyword search. **How does pricing work?** You pay $0.003 per product scraped and $0.05 per AI analysis report. There are no subscription fees — you only pay for what you use. **Does AI analysis require a paid API key?** OpenRouter offers a free tier with limited credits. Anthropic, Google AI, and OpenAI require paid API keys. Ollama is free with self-hosted models. AI analysis is completely optional. **Can I monitor prices across multiple eBay country domains?** Yes. Run separate searches with different `ebayDomain` values (e.g., `ebay.com`, `ebay.de`, `ebay.co.uk`) to compare pricing for the same product across regions. This is especially useful for international arbitrage, where currency differences and local supply create significant price gaps for identical items. ### Limitations - Maximum 200 products per run (eBay pagination limit) - Search results provide summary data; some fields (detailed description, full item specifics) are only available on product detail pages - Auction ending times may not always be available in search results - Seller information is not rendered in eBay's auction search result cards. Set `fetchDetails=true` to fetch seller info from individual listing pages (slower but complete). - Seller information may not be displayed for all listings in search results - eBay may occasionally show different layouts which could affect some field extraction - AI analysis requires an API key from OpenRouter, Anthropic, Google AI, or OpenAI (or a self-hosted Ollama instance) ### Legal and Compliance This actor scrapes publicly available data from eBay. Users are responsible for: - Complying with eBay's [Terms of Service](https://www.ebay.com/help/policies/member-behaviour-policies/user-agreement?id=4259) - Adhering to applicable data protection laws (GDPR, CCPA, etc.) - Using extracted data in accordance with all relevant regulations - Ensuring their use case does not violate any local or international laws eBay product listings are publicly accessible. This tool collects only publicly displayed information and does not access any private or authenticated data. The actor implements polite crawling practices with delays between requests. For questions or concerns, please open an issue on the [GitHub repository](https://github.com/nickcuper/apify-actors). # Actor input Schema ## `searchQuery` (type: `string`): Keyword(s) to search for on eBay (e.g. 'vintage Rolex', 'pokemon cards', 'Nintendo Switch OLED') ## `query` (type: `string`): CLI alias for searchQuery. Hidden from Console form. ## `q` (type: `string`): CLI alias for searchQuery. Hidden from Console form. ## `search` (type: `string`): CLI alias for searchQuery. Hidden from Console form. ## `keyword` (type: `string`): CLI alias for searchQuery. Hidden from Console form. ## `searchTerm` (type: `string`): CLI alias for searchQuery. Hidden from Console form. ## `productUrls` (type: `array`): Direct eBay listing URLs to scrape individually (e.g. https://www.ebay.com/itm/123456789012, https://www.ebay.co.uk/itm/234567890123). Use this instead of searchQuery when you already have specific listing IDs. Must be full /itm/ URLs — category or search URLs won't work. ## `urls` (type: `array`): CLI alias for productUrls. Hidden from Console form. ## `links` (type: `array`): CLI alias for productUrls. Hidden from Console form. ## `ebayDomain` (type: `string`): eBay country/regional domain to search. Prices and listings are localized per country — pick the market you want to scrape. ## `domain` (type: `string`): CLI alias for ebayDomain — accepts the same country domain values. Hidden from the Console form; exposed so `apify call -i '{"domain":"ebay.de"}'` works for users copying JSON between portfolio scrapers. ## `listingType` (type: `string`): Filter by sale format. Auction = bidding with end time; Buy It Now = fixed-price instant purchase; All = both. ## `sortBy` (type: `string`): Search result ordering. 'Best Match' = eBay's relevance algorithm (default). 'Ending Soonest' = auctions closing first (great for bargain-hunting). 'Newly Listed' = most recently posted. Price sorts apply to post-shipping total on ebay.com. ## `minPrice` (type: `number`): Minimum listing price in the domain's local currency (USD on ebay.com, GBP on ebay.co.uk, EUR on .de/.fr/.it/.es/.nl, AUD on .com.au, CAD on .ca). Example: 50 on ebay.com filters out listings under $50. Leave empty for no lower bound. ## `maxPrice` (type: `number`): Filter results by maximum price in the selected domain's local currency (USD on ebay.com, GBP on ebay.co.uk, etc.). ## `itemCondition` (type: `string`): Filter by item condition. Refurbished = certified-restored; Open Box = returned/unused; Used = pre-owned; New = sealed. ## `maxProducts` (type: `integer`): Maximum number of products to scrape (1-200). Also accepts 'maxItems' as an alias. ## `fetchDetails` (type: `boolean`): Visit each listing page to fetch full details (seller, full description, item specifics). Required for auction listings if you need `seller` field populated. Slower (~2-3x run time). Recommended for Buy It Now analysis too. ## `soldOnly` (type: `boolean`): Scrape only completed sales (eBay's LH\_Sold=1\&LH\_Complete=1 filter, ~90 day window) and emit a `sold_listings_summary` item with recommended list price (p60 of sold prices when n>=20, else median), p10/p25/p50/p75/p90 price band, median days-to-sell, market\_velocity ('hot' | 'steady' | 'slow' | 'cold'), and a 0-1 confidence\_score blending sample size + dispersion + date coverage. **v2.0: the summary also carries a `sold_listings_trend` block** with 7d/30d price deltas, velocity delta, and volume delta against prior runs (persisted in a named KV store, one history slot per searchQuery+domain). Individual sold listings bill at $0.005 each; summary is $0.10; trend bills $0.03 only when prior history exists. ## `soldDateLookback` (type: `integer`): How far back to assume eBay's LH\_Sold window covers when computing market\_velocity (sold-per-day). eBay typically retains 90 days of completed-sale data. Only used when soldOnly=true. Values: 30-365, default 90. ## `maxItems` (type: `integer`): Alternative name for Max Products — accepts the same values (1-200). Use either maxProducts or maxItems. ## `enableAiAnalysis` (type: `boolean`): Generate AI-powered market pricing analysis with price distribution, seller landscape, and buying recommendations ## `llmProvider` (type: `string`): AI backend for market/pricing analysis. 'OpenRouter' (default) is cheapest — Gemini Flash via OpenRouter is ~$0.001 per analysis. 'Anthropic' = Claude, 'Google AI' = Gemini direct, 'OpenAI' = GPT-4o mini, 'Ollama' = self-hosted (no API cost). Each provider needs its own API key field below. ## `llmModel` (type: `string`): Specific model to use. Leave empty for the provider default (google/gemini-2.0-flash-001 for OpenRouter, claude-sonnet-4-20250514 for Anthropic, gemini-2.0-flash for Google AI, gpt-4o-mini for OpenAI, llama3.1 for Ollama). ## `openrouterApiKey` (type: `string`): API key from openrouter.ai (required if using OpenRouter provider) ## `anthropicApiKey` (type: `string`): API key from console.anthropic.com (required if using Anthropic provider) ## `googleApiKey` (type: `string`): API key for Google AI (Gemini). Get one at aistudio.google.com/app/apikey ## `openaiApiKey` (type: `string`): API key from platform.openai.com (required if using OpenAI provider) ## `ollamaBaseUrl` (type: `string`): Base URL for Ollama API. Default: http://localhost:11434 ## `proxyConfiguration` (type: `object`): Proxy settings. eBay works with datacenter proxies — residential not required. ## Actor input object example ```json { "searchQuery": "pokemon cards", "ebayDomain": "ebay.com", "listingType": "all", "sortBy": "best_match", "itemCondition": "any", "maxProducts": 50, "fetchDetails": false, "soldOnly": false, "soldDateLookback": 90, "enableAiAnalysis": false, "llmProvider": "openrouter", "ollamaBaseUrl": "http://localhost:11434", "proxyConfiguration": { "useApifyProxy": true } } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQuery": "pokemon cards", "fetchDetails": false, "soldOnly": false, "ollamaBaseUrl": "http://localhost:11434", "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("harvestlab/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "searchQuery": "pokemon cards", "fetchDetails": False, "soldOnly": False, "ollamaBaseUrl": "http://localhost:11434", "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("harvestlab/ebay-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 '{ "searchQuery": "pokemon cards", "fetchDetails": false, "soldOnly": false, "ollamaBaseUrl": "http://localhost:11434", "proxyConfiguration": { "useApifyProxy": true } }' | apify call harvestlab/ebay-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=harvestlab/ebay-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "eBay Scraper - Prices, Sold Intelligence & Auction Data", "description": "The only eBay scraper with cross-run sold-price trend tracking. Covers 13 country domains, auction + BIN modes, sold-listings intelligence (recommended list price, p10-p90 band, velocity), AI analysis, 25+ fields. Pay-per-event.", "version": "2.0", "x-build-id": "2IeJtX2jcc5CqbYML" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/harvestlab~ebay-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-harvestlab-ebay-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/harvestlab~ebay-scraper/runs": { "post": { "operationId": "runs-sync-harvestlab-ebay-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/harvestlab~ebay-scraper/run-sync": { "post": { "operationId": "run-sync-harvestlab-ebay-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "searchQuery": { "title": "Search Query", "type": "string", "description": "Keyword(s) to search for on eBay (e.g. 'vintage Rolex', 'pokemon cards', 'Nintendo Switch OLED')" }, "query": { "title": "Search Query (CLI alias)", "type": "string", "description": "CLI alias for searchQuery. Hidden from Console form." }, "q": { "title": "Search Query (CLI alias)", "type": "string", "description": "CLI alias for searchQuery. Hidden from Console form." }, "search": { "title": "Search Query (CLI alias)", "type": "string", "description": "CLI alias for searchQuery. Hidden from Console form." }, "keyword": { "title": "Search Query (CLI alias)", "type": "string", "description": "CLI alias for searchQuery. Hidden from Console form." }, "searchTerm": { "title": "Search Query (CLI alias)", "type": "string", "description": "CLI alias for searchQuery. Hidden from Console form." }, "productUrls": { "title": "Product URLs", "type": "array", "description": "Direct eBay listing URLs to scrape individually (e.g. https://www.ebay.com/itm/123456789012, https://www.ebay.co.uk/itm/234567890123). Use this instead of searchQuery when you already have specific listing IDs. Must be full /itm/ URLs — category or search URLs won't work.", "items": { "type": "string" } }, "urls": { "title": "Product URLs (CLI alias)", "type": "array", "description": "CLI alias for productUrls. Hidden from Console form.", "items": { "type": "string" } }, "links": { "title": "Product URLs (CLI alias)", "type": "array", "description": "CLI alias for productUrls. Hidden from Console form.", "items": { "type": "string" } }, "ebayDomain": { "title": "eBay Domain", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.com.au", "ebay.ca", "ebay.nl", "ebay.at", "ebay.ch", "ebay.ie", "ebay.pl" ], "type": "string", "description": "eBay country/regional domain to search. Prices and listings are localized per country — pick the market you want to scrape.", "default": "ebay.com" }, "domain": { "title": "Domain (CLI alias for ebayDomain)", "type": "string", "description": "CLI alias for ebayDomain — accepts the same country domain values. Hidden from the Console form; exposed so `apify call -i '{\"domain\":\"ebay.de\"}'` works for users copying JSON between portfolio scrapers." }, "listingType": { "title": "Listing Type", "enum": [ "all", "auction", "buy_it_now" ], "type": "string", "description": "Filter by sale format. Auction = bidding with end time; Buy It Now = fixed-price instant purchase; All = both.", "default": "all" }, "sortBy": { "title": "Sort By", "enum": [ "best_match", "price_low", "price_high", "ending_soonest", "newly_listed" ], "type": "string", "description": "Search result ordering. 'Best Match' = eBay's relevance algorithm (default). 'Ending Soonest' = auctions closing first (great for bargain-hunting). 'Newly Listed' = most recently posted. Price sorts apply to post-shipping total on ebay.com.", "default": "best_match" }, "minPrice": { "title": "Minimum Price", "type": "number", "description": "Minimum listing price in the domain's local currency (USD on ebay.com, GBP on ebay.co.uk, EUR on .de/.fr/.it/.es/.nl, AUD on .com.au, CAD on .ca). Example: 50 on ebay.com filters out listings under $50. Leave empty for no lower bound." }, "maxPrice": { "title": "Maximum Price", "type": "number", "description": "Filter results by maximum price in the selected domain's local currency (USD on ebay.com, GBP on ebay.co.uk, etc.)." }, "itemCondition": { "title": "Item Condition", "enum": [ "any", "new", "open_box", "refurbished", "used" ], "type": "string", "description": "Filter by item condition. Refurbished = certified-restored; Open Box = returned/unused; Used = pre-owned; New = sealed.", "default": "any" }, "maxProducts": { "title": "Max Products", "minimum": 1, "maximum": 200, "type": "integer", "description": "Maximum number of products to scrape (1-200). Also accepts 'maxItems' as an alias.", "default": 50 }, "fetchDetails": { "title": "Fetch Detail Pages (Extra Fields)", "type": "boolean", "description": "Visit each listing page to fetch full details (seller, full description, item specifics). Required for auction listings if you need `seller` field populated. Slower (~2-3x run time). Recommended for Buy It Now analysis too.", "default": false }, "soldOnly": { "title": "Sold Listings Intelligence Mode", "type": "boolean", "description": "Scrape only completed sales (eBay's LH_Sold=1&LH_Complete=1 filter, ~90 day window) and emit a `sold_listings_summary` item with recommended list price (p60 of sold prices when n>=20, else median), p10/p25/p50/p75/p90 price band, median days-to-sell, market_velocity ('hot' | 'steady' | 'slow' | 'cold'), and a 0-1 confidence_score blending sample size + dispersion + date coverage. **v2.0: the summary also carries a `sold_listings_trend` block** with 7d/30d price deltas, velocity delta, and volume delta against prior runs (persisted in a named KV store, one history slot per searchQuery+domain). Individual sold listings bill at $0.005 each; summary is $0.10; trend bills $0.03 only when prior history exists.", "default": false }, "soldDateLookback": { "title": "Sold Date Lookback (Days)", "minimum": 30, "maximum": 365, "type": "integer", "description": "How far back to assume eBay's LH_Sold window covers when computing market_velocity (sold-per-day). eBay typically retains 90 days of completed-sale data. Only used when soldOnly=true. Values: 30-365, default 90.", "default": 90 }, "maxItems": { "title": "Max Items (alias for Max Products)", "minimum": 1, "maximum": 200, "type": "integer", "description": "Alternative name for Max Products — accepts the same values (1-200). Use either maxProducts or maxItems." }, "enableAiAnalysis": { "title": "Enable AI Analysis", "type": "boolean", "description": "Generate AI-powered market pricing analysis with price distribution, seller landscape, and buying recommendations", "default": false }, "llmProvider": { "title": "LLM Provider", "enum": [ "openrouter", "anthropic", "google", "openai", "ollama" ], "type": "string", "description": "AI backend for market/pricing analysis. 'OpenRouter' (default) is cheapest — Gemini Flash via OpenRouter is ~$0.001 per analysis. 'Anthropic' = Claude, 'Google AI' = Gemini direct, 'OpenAI' = GPT-4o mini, 'Ollama' = self-hosted (no API cost). Each provider needs its own API key field below.", "default": "openrouter" }, "llmModel": { "title": "LLM Model", "type": "string", "description": "Specific model to use. Leave empty for the provider default (google/gemini-2.0-flash-001 for OpenRouter, claude-sonnet-4-20250514 for Anthropic, gemini-2.0-flash for Google AI, gpt-4o-mini for OpenAI, llama3.1 for Ollama)." }, "openrouterApiKey": { "title": "OpenRouter API Key", "type": "string", "description": "API key from openrouter.ai (required if using OpenRouter provider)" }, "anthropicApiKey": { "title": "Anthropic API Key", "type": "string", "description": "API key from console.anthropic.com (required if using Anthropic provider)" }, "googleApiKey": { "title": "Google AI API Key", "type": "string", "description": "API key for Google AI (Gemini). Get one at aistudio.google.com/app/apikey" }, "openaiApiKey": { "title": "OpenAI API Key", "type": "string", "description": "API key from platform.openai.com (required if using OpenAI provider)" }, "ollamaBaseUrl": { "title": "Ollama Base URL", "type": "string", "description": "Base URL for Ollama API. Default: http://localhost:11434" }, "proxyConfiguration": { "title": "Proxy Configuration", "type": "object", "description": "Proxy settings. eBay works with datacenter proxies — residential not required." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```