{"openapi":"3.1.0","info":{"title":"eBay Sold Listings API","version":"1.0.0","description":"SoldComps returns real eBay completed sales — price, condition, date, seller — from a single GET request. No scraping setup, no stale cache, no OAuth dance.\n\n## Authentication\n\nAll requests require a bearer token:\n\n```\nAuthorization: Bearer sc_YOUR_KEY_HERE\n```\n\nAPI keys start with `sc_`. [Create a free account](https://sold-comps.com/signup) to get one, or find your key in the [dashboard](https://sold-comps.com/dashboard). The free plan includes 50 requests/month — no credit card required.\n\n## Quick Start\n\n```bash\ncurl -H \"Authorization: Bearer sc_YOUR_KEY_HERE\" \\\n  \"https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&count=10\"\n```\n\n```python\nimport requests\n\nresp = requests.get(\n    \"https://api.sold-comps.com/v1/scrape\",\n    headers={\"Authorization\": \"Bearer sc_YOUR_KEY_HERE\"},\n    params={\"keyword\": \"iphone 15 pro\", \"count\": 10},\n)\ndata = resp.json()\nprint(f\"Found {data['totalItems']} sold listings\")\n```\n\n```javascript\nconst res = await fetch(\n  \"https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&count=10\",\n  { headers: { Authorization: \"Bearer sc_YOUR_KEY_HERE\" } }\n);\nconst data = await res.json();\nconsole.log(`Found ${data.totalItems} sold listings`);\n```\n\n```go\nreq, _ := http.NewRequest(\"GET\",\n  \"https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&count=10\", nil)\nreq.Header.Set(\"Authorization\", \"Bearer sc_YOUR_KEY_HERE\")\nresp, _ := http.DefaultClient.Do(req)\ndefer resp.Body.Close()\n```\n\n## Pagination\n\nEach request returns one page (up to 240 items). Use the `page` parameter to fetch subsequent pages and check `hasNextPage` in the response to detect if more results exist.\n\n```\nGET /v1/scrape?keyword=iphone+15+pro&page=1\nGET /v1/scrape?keyword=iphone+15+pro&page=2\n```\n\n## Catalog matching with `epid`\n\nEach result includes an optional `epid` field — eBay's catalog product ID. When a listing is matched to eBay's product catalog, every seller's listing for the same variant shares the same `epid` (e.g. all \"iPhone 15 Pro Max 512GB Natural Titanium\" sales return the same value). Use it to group comps across sellers without fuzzy title matching.\n\n- `epid` is a numeric string (`\"20049285656\"`) or `null` when the listing has no catalog match.\n- Coverage varies by category: 70–95% for popular electronics, books, and collectibles; near 0% for one-of-a-kind / used-only items.\n- The id is stable — safe to store as a foreign key in your own database.\n\n## Listing thumbnail: `thumbnailUrl`\n\nEach result includes a `thumbnailUrl` pointing at the 500px image eBay serves on the search results page (hosted on `i.ebayimg.com`). Useful for rendering comps in your own UI without hitting the listing page. `null` when the listing has no product image.\n\n- The URL is stable for the lifetime of the listing — but eBay can rotate or retire the asset once the listing is removed, so rehost or proxy it if you need durable storage.\n- Resolution is fixed at 500px. eBay's CDN supports other size suffixes (`s-l140`, `s-l225`, `s-l1600`) if you swap the path segment client-side.\n\n## Item condition: `condition` and `conditionId`\n\nEach result includes two condition fields:\n\n- `condition` — the **localized display label** as eBay rendered it on the search result card. Example values: `\"Brand New\"`, `\"Pre-Owned\"`, `\"Gebraucht\"`, `\"Neuf\"`, `\"Nuovo\"`, `\"Nur Ersatzteile\"`, `\"Open box\"`. Labels vary by eBay site language and by category. `null` when the listing has no condition shown. This is the authoritative field — what the buyer actually saw.\n- `conditionId` — eBay's **numeric condition ID** (e.g. `1000` for New, `3000` for Used, `7000` for For parts), resolved from the `condition` label via a best-effort static lookup table covering ~60 labels across all 8 eBay locales. Use this to bucket items by condition tier without locale-specific string matching.\n\nImportant notes about `conditionId`:\n\n- **Best-effort**: `conditionId` is a convenience layer over the localized `condition` label. Unknown or newly-introduced labels resolve to `null` (the `condition` string is still returned). The mapping is updated manually as new labels surface — do not treat `null` as \"no condition data\"; check `condition` first.\n- **Common IDs**: `1000` New, `1500` New Other / Open box, `1750` New with defects, `2000`–`2030` Certified / Excellent / Very Good / Good Refurbished, `2500` Seller Refurbished, `2750` Like New, `2990`/`3010` Pre-owned Excellent/Fair (apparel), `3000` Used / Pre-Owned, `4000` Very Good, `5000` Good, `6000` Acceptable, `7000` For parts or not working.\n- Full reference: [eBay condition ID values](https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html).\n\n## Seller type: `sellerType`\n\nEU eBay sites (ebay.de, .fr, .it, .es) label each listing as sold by a private individual or a commercial/professional seller. SoldComps normalizes these localized labels to `\"private\"` or `\"business\"`. Non-EU sites (ebay.com, .co.uk, .ca, .com.au) do not surface this data — `sellerType` will be `null`.\n\nUse the `sellerType` query parameter to filter results post-scrape:\n\n```\nGET /v1/scrape?keyword=iphone+14&ebaySite=ebay.de&sellerType=private\n```\n\nWhen `sellerType` is set on a non-EU site, no filtering is applied (all items returned). When set on an EU site, sponsored cards and any items with no recognizable seller-type label are excluded.\n\n## Rate Limits & Quotas\n\nLimits are enforced per billing period. When exceeded the API returns `429` with details in the body and `X-Usage-*` headers on every response.\n\n| Plan | Monthly | Daily | Per minute |\n|------|---------|-------|------------|\n| Free | 25 | 5 | 1 |\n| Starter | 500 | — | 30 |\n| Growth | 2,000 | — | 60 |\n| Scale | 5,000 | — | 120 |\n\nUpgrade anytime at [sold-comps.com/dashboard](https://sold-comps.com/dashboard).\n\n## Error Codes\n\n| Status | Meaning |\n|--------|---------|\n| `400` | Bad request — missing or invalid parameters |\n| `401` | Unauthorized — missing, invalid, or revoked API key |\n| `429` | Rate limit or quota exceeded — check response body for which limit was hit and when it resets |\n| `500` | Server error — scrape failed; retry with exponential backoff |\n\n## Category IDs\n\nPass a category ID as the `categoryId` parameter to narrow results to a specific eBay category. Use `\"0\"` (default) to search across all categories.\n\nBrowse and search all 17,000+ eBay category IDs at [sold-comps.com/ebay-categories](https://sold-comps.com/ebay-categories).\n\nCommon top-level categories:\n\n| ID | Category |\n|----|----------|\n| `0` | All Categories |\n| `293` | Consumer Electronics |\n| `15032` | Cell Phones & Accessories |\n| `58058` | Computers/Tablets & Networking |\n| `1249` | Video Games & Consoles |\n| `11450` | Clothing, Shoes & Accessories |\n| `1` | Collectibles |\n| `64482` | Sports Mem, Cards & Fan Shop |\n| `220` | Toys & Hobbies |\n| `11700` | Home & Garden |\n| `281` | Jewelry & Watches |\n\nFor subcategory-level filtering (e.g., `9355` for Cell Phones & Smartphones), use the [category browser](https://sold-comps.com/ebay-categories) to search by name and copy the ID."},"servers":[{"url":"http://localhost:3000","description":"Local"},{"url":"https://api.sold-comps.com","description":"Production"}],"tags":[{"name":"Max Mode","description":"**Async, server-paginated sweep.** Submit a keyword once and the SoldComps worker paginates for you — no client-side loop, no Cloudflare-style edge timeouts. Poll for the result, get it emailed as a CSV, or fetch it from a signed download URL.\n\n### How it counts\n\nEach **successfully** scraped page debits **1 request** from your monthly quota — exactly the same rate as if you'd called `/v1/scrape?page=1` through `/v1/scrape?page=50` yourself. Failed pages don't debit. A 50-page job costs up to 50 requests; a 100-page job costs up to 100. The worker stops cleanly if you run out of quota and returns whatever it collected so far.\n\n### Submit / poll / receive\n\n1. `POST /v1/scrape/max` with your `keyword`, `maxPages` (1–100, default 50), and a `resultType`. Returns `202` with a `jobId` in under 500ms.\n2. `GET /v1/scrape/max/results/{jobId}` returns either a running-status payload (with progress counters) or, once the job hits a terminal state, the final result.\n3. `DELETE /v1/scrape/max/{jobId}` cancels an in-flight job. Already-debited quota is not refunded.\n\n### Delivery modes — pick one via `resultType`\n\n- **`inline`** *(default)* — the final `GET /results` response includes `items[]`.\n- **`email`** — when the job completes, we email a CSV to the address on file for your account (override with `emailTo`). CSVs ≤5MB are attached; larger results are sent as a signed 24-hour download link.\n- **`download`** — the final `GET /results` includes a signed `downloadUrl` pointing at a CSV stream of the full result. 24-hour TTL.\n\n### Constraints\n\n- **One active Max Mode job per user.** Submitting a second while one is running returns `409` with the existing `jobId`.\n- Pass `Idempotency-Key` on submit to dedup re-submissions inside a 24-hour window.\n- `count` is not accepted — every page pulls the full 240 items (the whole point of Max Mode is exhaustion).\n- Results expire 30 days after completion; `GET /results` returns `410 Gone` after that."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"Your SoldComps API key (starts with sc_). Create one at https://sold-comps.com/dashboard."}},"schemas":{},"parameters":{}},"paths":{"/public/scrape":{"get":{"tags":["Scrape"],"summary":"Scrape eBay sold listings","description":"Returns one page of real eBay sold listing data for a given keyword — price, seller, shipping, sold date, and condition. Each request returns up to 240 listings (configurable via `count`). Use the `page` param to paginate through more results.","parameters":[{"schema":{"type":"string","minLength":1,"description":"eBay search keyword","example":"iphone 15 pro"},"required":true,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number of eBay results to fetch (default: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":240,"description":"Max items per page (1–240). When omitted, defaults to 240 on standard tiers and 60 on custom tiers.","example":240},"required":false,"name":"count","in":"query"},{"schema":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com","description":"eBay domain to scrape","example":"ebay.com"},"required":false,"name":"ebaySite","in":"query"},{"schema":{"type":"string","default":"0","description":"eBay category ID (_sacat). Use \"0\" for all categories.","example":"9355"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently","description":"Sort order for results","example":"endedRecently"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price filter (in listing currency)","example":100},"required":false,"name":"minPrice","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price filter (in listing currency)","example":800},"required":false,"name":"maxPrice","in":"query"},{"schema":{"type":"string","enum":["default","domestic","worldwide"],"default":"default","description":"Item location filter"},"required":false,"name":"itemLocation","in":"query"},{"schema":{"type":"string","enum":["any","new","used"],"default":"any","description":"Item condition filter"},"required":false,"name":"itemCondition","in":"query"},{"schema":{"type":"string","enum":["private","business"],"description":"Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). When set on a non-EU site, no filtering is applied (all results returned). When set on an EU site, items with null sellerType (e.g. sponsored cards) are excluded."},"required":false,"name":"sellerType","in":"query"}],"responses":{"200":{"description":"Sold listings","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string"},"page":{"type":"number","description":"Page number that was fetched"},"totalItems":{"type":"number","description":"Number of items returned on this page"},"hasNextPage":{"type":"boolean","description":"Whether more pages are available"},"autoSelectedCategory":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"9355"},"name":{"type":"string","example":"Cell Phones & Smartphones"}},"required":["id","name"],"description":"Category auto-selected by eBay for this search. Present when eBay narrows a categoryId=0 search to a specific category. null when no auto-selection occurs or when a specific categoryId was requested."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"256123456789"},"url":{"type":"string","example":"https://www.ebay.com/itm/256123456789?nordt=true"},"thumbnailUrl":{"type":"string","nullable":true,"description":"URL of the listing thumbnail image from the eBay search results page (500px). Hosted on i.ebayimg.com. null when no product image is available.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp"},"fullResThumbnailUrl":{"type":"string","nullable":true,"description":"Full-resolution version of thumbnailUrl (~1600px). Derived by replacing the size suffix (s-l500, s-l140, etc.) with s-l1600. The eBay CDN returns the highest available resolution up to 1600px. null when thumbnailUrl is null.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp"},"epid":{"type":"string","nullable":true,"description":"eBay catalog product ID (epid) when the listing is matched to a product in eBay's catalog. Stable across sellers for the same product variant — useful for grouping comps. null when the listing has no catalog match.","example":"20049285656"},"title":{"type":"string","nullable":true,"example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"condition":{"type":"string","nullable":true,"description":"Item condition label as displayed on eBay (localized per site). e.g. \"Pre-Owned\", \"Gebraucht\", \"Brand New\", \"Nur Ersatzteile\". Labels vary by eBay site language and category. null when the listing has no condition listed. See https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html for the full condition taxonomy.","example":"Pre-Owned"},"conditionId":{"type":"integer","nullable":true,"description":"eBay numeric condition ID resolved from the condition label via best-effort lookup. null when the label is unrecognized. Common IDs: 1000 (New), 1500 (Open box / New Other), 2000-2030 (Refurbished tiers), 3000 (Used / Pre-Owned), 7000 (For parts). Full reference: https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html","example":3000},"sellerType":{"type":"string","nullable":true,"enum":["private","business"],"description":"Seller type on EU eBay sites (ebay.de, .fr, .it, .es): \"private\" for individual sellers, \"business\" for commercial/professional sellers. null on non-EU sites (ebay.com, .co.uk, .ca, .com.au) where eBay does not surface this data on search results.","example":"private"},"buyingFormat":{"type":"string","nullable":true,"enum":["auction","buyItNow","auctionWithBIN"],"description":"How the item was listed. \"auction\" = competitive bidding only, \"buyItNow\" = fixed price (includes Best Offer listings), \"auctionWithBIN\" = auction that also had a Buy It Now option. null when the listing type could not be determined from the search result.","example":"auction"},"bestOfferAccepted":{"type":"boolean","description":"When true, the seller accepted a best offer below the original asking price. soldPrice is the actual accepted amount; the original asking price was higher (visible as a strikethrough on eBay but not exposed in this API). Detected when a listing shows \"or Best Offer\" text AND a strikethrough original price.","example":false},"bidCount":{"type":"integer","nullable":true,"description":"Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.","example":12},"categoryId":{"type":"string","example":"9355"},"endedAt":{"type":"string","description":"ISO 8601 sold date","example":"2026-03-10T18:42:00.000Z"},"soldPrice":{"type":"string","nullable":true,"example":"899.99"},"soldCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingPrice":{"type":"string","nullable":true,"example":"0.00"},"shippingCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingType":{"type":"string","nullable":true,"enum":["free","paid","pickup","unknown"]},"totalPrice":{"type":"string","nullable":true,"example":"899.99"},"sellerUsername":{"type":"string","nullable":true,"example":"top-deals-store"},"sellerPositivePercent":{"type":"number","nullable":true,"example":99.8},"sellerFeedbackScore":{"type":"number","nullable":true,"example":14200},"itemLocation":{"type":"string","nullable":true,"description":"Seller location country as shown on the eBay search results page. Localized per eBay site language (e.g., \"United States\" on ebay.com, \"Großbritannien\" on ebay.de, \"Stati Uniti\" on ebay.it). null when eBay does not display location (always null on ebay.co.uk, and omitted on some listings across other sites).","example":"United States"},"scrapedAt":{"type":"string","example":"2026-03-14T21:00:00.000Z"}},"required":["itemId","url","thumbnailUrl","fullResThumbnailUrl","epid","title","condition","conditionId","sellerType","buyingFormat","bestOfferAccepted","bidCount","categoryId","endedAt","soldPrice","soldCurrency","shippingPrice","shippingCurrency","shippingType","totalPrice","sellerUsername","sellerPositivePercent","sellerFeedbackScore","itemLocation","scrapedAt"]}}},"required":["keyword","page","totalItems","hasNextPage","autoSelectedCategory","items"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit exceeded (5 req/day or 20 req/month per IP)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"limit_type":{"type":"string","enum":["daily","monthly"]},"limit":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"reset_at":{"type":"string","description":"ISO 8601 UTC timestamp when the window resets"}},"required":["error","limit_type","limit","used","remaining","reset_at"]}}}},"500":{"description":"Scrape failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay served a bot challenge that all fetch layers failed to bypass","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape/category":{"get":{"tags":["Direct Access"],"summary":"Browse eBay category sold listings (Direct SaaS)","description":"Returns one page of real eBay sold listing data for an entire category, without a keyword. Pass a `categoryId` (eBay `_sacat` parameter) and optionally filter by price, condition, or seller type. Uses the same `/sch/i.html` search path with an empty keyword internally — the HTML structure and all filters behave identically to `/v1/scrape`. Requires a SoldComps API key via `Authorization: Bearer sc_...`. Rate limited per plan (1–120 req/min). Monthly quota enforced per billing period. Each page debits 1 request from your quota.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","description":"eBay category ID (_sacat). Required. Must not be \"0\".","example":"27386"},"required":true,"name":"categoryId","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number of eBay results to fetch (default: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":240,"description":"Max items per page (1–240). Defaults to 240 on standard tiers, 60 on custom tiers.","example":240},"required":false,"name":"count","in":"query"},{"schema":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com","description":"eBay domain to scrape","example":"ebay.com"},"required":false,"name":"ebaySite","in":"query"},{"schema":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently","description":"Sort order for results","example":"endedRecently"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price filter (in listing currency)","example":100},"required":false,"name":"minPrice","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price filter (in listing currency)","example":800},"required":false,"name":"maxPrice","in":"query"},{"schema":{"type":"string","enum":["default","domestic","worldwide"],"default":"default","description":"Item location filter"},"required":false,"name":"itemLocation","in":"query"},{"schema":{"type":"string","enum":["any","new","used"],"default":"any","description":"Item condition filter"},"required":false,"name":"itemCondition","in":"query"},{"schema":{"type":"string","enum":["private","business"],"description":"Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). When set on a non-EU site, no filtering is applied."},"required":false,"name":"sellerType","in":"query"}],"responses":{"200":{"description":"Sold listings for the category","content":{"application/json":{"schema":{"type":"object","properties":{"categoryId":{"type":"string"},"page":{"type":"number","description":"Page number that was fetched"},"totalItems":{"type":"number","description":"Number of items returned on this page"},"hasNextPage":{"type":"boolean","description":"Whether more pages are available"},"autoSelectedCategory":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"9355"},"name":{"type":"string","example":"Cell Phones & Smartphones"}},"required":["id","name"],"description":"Category auto-selected by eBay for this search. Present when eBay narrows a categoryId=0 search to a specific category. null when no auto-selection occurs or when a specific categoryId was requested."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"256123456789"},"url":{"type":"string","example":"https://www.ebay.com/itm/256123456789?nordt=true"},"thumbnailUrl":{"type":"string","nullable":true,"description":"URL of the listing thumbnail image from the eBay search results page (500px). Hosted on i.ebayimg.com. null when no product image is available.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp"},"fullResThumbnailUrl":{"type":"string","nullable":true,"description":"Full-resolution version of thumbnailUrl (~1600px). Derived by replacing the size suffix (s-l500, s-l140, etc.) with s-l1600. The eBay CDN returns the highest available resolution up to 1600px. null when thumbnailUrl is null.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp"},"epid":{"type":"string","nullable":true,"description":"eBay catalog product ID (epid) when the listing is matched to a product in eBay's catalog. Stable across sellers for the same product variant — useful for grouping comps. null when the listing has no catalog match.","example":"20049285656"},"title":{"type":"string","nullable":true,"example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"condition":{"type":"string","nullable":true,"description":"Item condition label as displayed on eBay (localized per site). e.g. \"Pre-Owned\", \"Gebraucht\", \"Brand New\", \"Nur Ersatzteile\". Labels vary by eBay site language and category. null when the listing has no condition listed. See https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html for the full condition taxonomy.","example":"Pre-Owned"},"conditionId":{"type":"integer","nullable":true,"description":"eBay numeric condition ID resolved from the condition label via best-effort lookup. null when the label is unrecognized. Common IDs: 1000 (New), 1500 (Open box / New Other), 2000-2030 (Refurbished tiers), 3000 (Used / Pre-Owned), 7000 (For parts). Full reference: https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html","example":3000},"sellerType":{"type":"string","nullable":true,"enum":["private","business"],"description":"Seller type on EU eBay sites (ebay.de, .fr, .it, .es): \"private\" for individual sellers, \"business\" for commercial/professional sellers. null on non-EU sites (ebay.com, .co.uk, .ca, .com.au) where eBay does not surface this data on search results.","example":"private"},"buyingFormat":{"type":"string","nullable":true,"enum":["auction","buyItNow","auctionWithBIN"],"description":"How the item was listed. \"auction\" = competitive bidding only, \"buyItNow\" = fixed price (includes Best Offer listings), \"auctionWithBIN\" = auction that also had a Buy It Now option. null when the listing type could not be determined from the search result.","example":"auction"},"bestOfferAccepted":{"type":"boolean","description":"When true, the seller accepted a best offer below the original asking price. soldPrice is the actual accepted amount; the original asking price was higher (visible as a strikethrough on eBay but not exposed in this API). Detected when a listing shows \"or Best Offer\" text AND a strikethrough original price.","example":false},"bidCount":{"type":"integer","nullable":true,"description":"Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.","example":12},"categoryId":{"type":"string","example":"9355"},"endedAt":{"type":"string","description":"ISO 8601 sold date","example":"2026-03-10T18:42:00.000Z"},"soldPrice":{"type":"string","nullable":true,"example":"899.99"},"soldCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingPrice":{"type":"string","nullable":true,"example":"0.00"},"shippingCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingType":{"type":"string","nullable":true,"enum":["free","paid","pickup","unknown"]},"totalPrice":{"type":"string","nullable":true,"example":"899.99"},"sellerUsername":{"type":"string","nullable":true,"example":"top-deals-store"},"sellerPositivePercent":{"type":"number","nullable":true,"example":99.8},"sellerFeedbackScore":{"type":"number","nullable":true,"example":14200},"itemLocation":{"type":"string","nullable":true,"description":"Seller location country as shown on the eBay search results page. Localized per eBay site language (e.g., \"United States\" on ebay.com, \"Großbritannien\" on ebay.de, \"Stati Uniti\" on ebay.it). null when eBay does not display location (always null on ebay.co.uk, and omitted on some listings across other sites).","example":"United States"},"scrapedAt":{"type":"string","example":"2026-03-14T21:00:00.000Z"}},"required":["itemId","url","thumbnailUrl","fullResThumbnailUrl","epid","title","condition","conditionId","sellerType","buyingFormat","bestOfferAccepted","bidCount","categoryId","endedAt","soldPrice","soldCurrency","shippingPrice","shippingCurrency","shippingType","totalPrice","sellerUsername","sellerPositivePercent","sellerFeedbackScore","itemLocation","scrapedAt"]}}},"required":["categoryId","page","totalItems","hasNextPage","autoSelectedCategory","items"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"plan":{"type":"string"},"limit":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"reset_at":{"type":"string"},"retry_after":{"type":"number"},"upgrade_url":{"type":"string"}},"required":["error","plan","limit"]}}}},"500":{"description":"Scrape failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay served a bot challenge that all fetch layers failed to bypass","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape/max":{"post":{"tags":["Max Mode"],"summary":"Submit an async paginated scrape job","security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string","minLength":1,"example":"rtx 4090"},"maxPages":{"type":"integer","minimum":1,"maximum":100,"default":50,"example":50},"resultType":{"type":"string","enum":["inline","email","download"],"default":"inline"},"emailTo":{"type":"string","format":"email"},"ebaySite":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com"},"categoryId":{"type":"string","default":"0"},"sortOrder":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently"},"minPrice":{"type":"number","nullable":true,"minimum":0},"maxPrice":{"type":"number","nullable":true,"minimum":0},"itemLocation":{"type":"string","enum":["default","domestic","worldwide"],"default":"default"},"itemCondition":{"type":"string","enum":["any","new","used"],"default":"any"},"sellerType":{"type":"string","enum":["private","business"]},"daysToScrape":{"type":"integer","minimum":1,"maximum":365,"default":90}},"required":["keyword"]}}}},"responses":{"202":{"description":"Job queued","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"},"resultsUrl":{"type":"string"},"estimatedSeconds":{"type":"number"}},"required":["jobId","status","resultsUrl","estimatedSeconds"]}}}},"400":{"description":"Invalid params","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"A maxMode job is already active for this user","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"jobId":{"type":"string"},"status":{"type":"string"}},"required":["error","jobId","status"]}}}},"429":{"description":"Monthly quota exhausted","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape/max/results/{jobId}":{"get":{"tags":["Max Mode"],"summary":"Fetch job status (while running) or final result (terminal)","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path"}],"responses":{"200":{"description":"Job status or result","content":{"application/json":{"schema":{"nullable":true}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"410":{"description":"Job expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape/max/{jobId}":{"delete":{"tags":["Max Mode"],"summary":"Cancel an in-progress job","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path"}],"responses":{"200":{"description":"Cancelled","content":{"application/json":{"schema":{"type":"object","properties":{"jobId":{"type":"string"},"status":{"type":"string"}},"required":["jobId","status"]}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"409":{"description":"Already terminal","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape/max/{jobId}/download.csv":{"get":{"tags":["Max Mode"],"summary":"Stream the job result as CSV (signed token only)","parameters":[{"schema":{"type":"string","minLength":1},"required":true,"name":"jobId","in":"path"},{"schema":{"type":"string"},"required":false,"name":"token","in":"query"}],"responses":{"200":{"description":"CSV stream"},"401":{"description":"Missing, invalid, or expired token","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"404":{"description":"Job not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"410":{"description":"Job expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/v1/scrape":{"get":{"tags":["Direct Access"],"summary":"Scrape eBay sold listings (Direct SaaS)","description":"Returns one page of real eBay sold listing data for a given keyword. Requires a SoldComps API key via `Authorization: Bearer sc_...`. Rate limited per plan (1–120 req/min). Monthly quota enforced per billing period.","security":[{"bearerAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"description":"eBay search keyword","example":"iphone 15 pro"},"required":true,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number of eBay results to fetch (default: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":240,"description":"Max items per page (1–240). When omitted, defaults to 240 on standard tiers and 60 on custom tiers.","example":240},"required":false,"name":"count","in":"query"},{"schema":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com","description":"eBay domain to scrape","example":"ebay.com"},"required":false,"name":"ebaySite","in":"query"},{"schema":{"type":"string","default":"0","description":"eBay category ID (_sacat). Use \"0\" for all categories.","example":"9355"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently","description":"Sort order for results","example":"endedRecently"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price filter (in listing currency)","example":100},"required":false,"name":"minPrice","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price filter (in listing currency)","example":800},"required":false,"name":"maxPrice","in":"query"},{"schema":{"type":"string","enum":["default","domestic","worldwide"],"default":"default","description":"Item location filter"},"required":false,"name":"itemLocation","in":"query"},{"schema":{"type":"string","enum":["any","new","used"],"default":"any","description":"Item condition filter"},"required":false,"name":"itemCondition","in":"query"},{"schema":{"type":"string","enum":["private","business"],"description":"Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). When set on a non-EU site, no filtering is applied (all results returned). When set on an EU site, items with null sellerType (e.g. sponsored cards) are excluded."},"required":false,"name":"sellerType","in":"query"}],"responses":{"200":{"description":"Sold listings","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string"},"page":{"type":"number","description":"Page number that was fetched"},"totalItems":{"type":"number","description":"Number of items returned on this page"},"hasNextPage":{"type":"boolean","description":"Whether more pages are available"},"autoSelectedCategory":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"9355"},"name":{"type":"string","example":"Cell Phones & Smartphones"}},"required":["id","name"],"description":"Category auto-selected by eBay for this search. Present when eBay narrows a categoryId=0 search to a specific category. null when no auto-selection occurs or when a specific categoryId was requested."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"256123456789"},"url":{"type":"string","example":"https://www.ebay.com/itm/256123456789?nordt=true"},"thumbnailUrl":{"type":"string","nullable":true,"description":"URL of the listing thumbnail image from the eBay search results page (500px). Hosted on i.ebayimg.com. null when no product image is available.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp"},"fullResThumbnailUrl":{"type":"string","nullable":true,"description":"Full-resolution version of thumbnailUrl (~1600px). Derived by replacing the size suffix (s-l500, s-l140, etc.) with s-l1600. The eBay CDN returns the highest available resolution up to 1600px. null when thumbnailUrl is null.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp"},"epid":{"type":"string","nullable":true,"description":"eBay catalog product ID (epid) when the listing is matched to a product in eBay's catalog. Stable across sellers for the same product variant — useful for grouping comps. null when the listing has no catalog match.","example":"20049285656"},"title":{"type":"string","nullable":true,"example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"condition":{"type":"string","nullable":true,"description":"Item condition label as displayed on eBay (localized per site). e.g. \"Pre-Owned\", \"Gebraucht\", \"Brand New\", \"Nur Ersatzteile\". Labels vary by eBay site language and category. null when the listing has no condition listed. See https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html for the full condition taxonomy.","example":"Pre-Owned"},"conditionId":{"type":"integer","nullable":true,"description":"eBay numeric condition ID resolved from the condition label via best-effort lookup. null when the label is unrecognized. Common IDs: 1000 (New), 1500 (Open box / New Other), 2000-2030 (Refurbished tiers), 3000 (Used / Pre-Owned), 7000 (For parts). Full reference: https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html","example":3000},"sellerType":{"type":"string","nullable":true,"enum":["private","business"],"description":"Seller type on EU eBay sites (ebay.de, .fr, .it, .es): \"private\" for individual sellers, \"business\" for commercial/professional sellers. null on non-EU sites (ebay.com, .co.uk, .ca, .com.au) where eBay does not surface this data on search results.","example":"private"},"buyingFormat":{"type":"string","nullable":true,"enum":["auction","buyItNow","auctionWithBIN"],"description":"How the item was listed. \"auction\" = competitive bidding only, \"buyItNow\" = fixed price (includes Best Offer listings), \"auctionWithBIN\" = auction that also had a Buy It Now option. null when the listing type could not be determined from the search result.","example":"auction"},"bestOfferAccepted":{"type":"boolean","description":"When true, the seller accepted a best offer below the original asking price. soldPrice is the actual accepted amount; the original asking price was higher (visible as a strikethrough on eBay but not exposed in this API). Detected when a listing shows \"or Best Offer\" text AND a strikethrough original price.","example":false},"bidCount":{"type":"integer","nullable":true,"description":"Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.","example":12},"categoryId":{"type":"string","example":"9355"},"endedAt":{"type":"string","description":"ISO 8601 sold date","example":"2026-03-10T18:42:00.000Z"},"soldPrice":{"type":"string","nullable":true,"example":"899.99"},"soldCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingPrice":{"type":"string","nullable":true,"example":"0.00"},"shippingCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingType":{"type":"string","nullable":true,"enum":["free","paid","pickup","unknown"]},"totalPrice":{"type":"string","nullable":true,"example":"899.99"},"sellerUsername":{"type":"string","nullable":true,"example":"top-deals-store"},"sellerPositivePercent":{"type":"number","nullable":true,"example":99.8},"sellerFeedbackScore":{"type":"number","nullable":true,"example":14200},"itemLocation":{"type":"string","nullable":true,"description":"Seller location country as shown on the eBay search results page. Localized per eBay site language (e.g., \"United States\" on ebay.com, \"Großbritannien\" on ebay.de, \"Stati Uniti\" on ebay.it). null when eBay does not display location (always null on ebay.co.uk, and omitted on some listings across other sites).","example":"United States"},"scrapedAt":{"type":"string","example":"2026-03-14T21:00:00.000Z"}},"required":["itemId","url","thumbnailUrl","fullResThumbnailUrl","epid","title","condition","conditionId","sellerType","buyingFormat","bestOfferAccepted","bidCount","categoryId","endedAt","soldPrice","soldCurrency","shippingPrice","shippingCurrency","shippingType","totalPrice","sellerUsername","sellerPositivePercent","sellerFeedbackScore","itemLocation","scrapedAt"]}}},"required":["keyword","page","totalItems","hasNextPage","autoSelectedCategory","items"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Rate limit or quota exceeded","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"plan":{"type":"string"},"limit":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"reset_at":{"type":"string"},"retry_after":{"type":"number"},"upgrade_url":{"type":"string"}},"required":["error","plan","limit"]}}}},"500":{"description":"Scrape failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay served a bot challenge that all fetch layers failed to bypass","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/rapidapi/scrape-ebay":{"get":{"tags":["RapidAPI"],"summary":"Scrape eBay sold listings (RapidAPI)","description":"**For RapidAPI subscribers only.** Requires a valid `X-RapidAPI-Key` header — subscribe at rapidapi.com/soldcomps/ebay-sold-listings.\n\nReturns one page of real eBay sold listing data for a given keyword — price, seller, shipping, sold date, and condition. Each request returns up to 240 listings (configurable via `count`). Use the `page` param to paginate through more results.\n\nBilled as one request against your monthly plan quota. Overage rates apply once your quota is exhausted.","parameters":[{"schema":{"type":"string","minLength":1,"description":"eBay search keyword","example":"iphone 15 pro"},"required":true,"name":"keyword","in":"query"},{"schema":{"type":"integer","minimum":1,"default":1,"description":"Page number of eBay results to fetch (default: 1)","example":1},"required":false,"name":"page","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":240,"description":"Max items per page (1–240). When omitted, defaults to 240 on standard tiers and 60 on custom tiers.","example":240},"required":false,"name":"count","in":"query"},{"schema":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com","description":"eBay domain to scrape","example":"ebay.com"},"required":false,"name":"ebaySite","in":"query"},{"schema":{"type":"string","default":"0","description":"eBay category ID (_sacat). Use \"0\" for all categories.","example":"9355"},"required":false,"name":"categoryId","in":"query"},{"schema":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently","description":"Sort order for results","example":"endedRecently"},"required":false,"name":"sortOrder","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Minimum price filter (in listing currency)","example":100},"required":false,"name":"minPrice","in":"query"},{"schema":{"type":"number","nullable":true,"minimum":0,"description":"Maximum price filter (in listing currency)","example":800},"required":false,"name":"maxPrice","in":"query"},{"schema":{"type":"string","enum":["default","domestic","worldwide"],"default":"default","description":"Item location filter"},"required":false,"name":"itemLocation","in":"query"},{"schema":{"type":"string","enum":["any","new","used"],"default":"any","description":"Item condition filter"},"required":false,"name":"itemCondition","in":"query"},{"schema":{"type":"string","enum":["private","business"],"description":"Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). When set on a non-EU site, no filtering is applied (all results returned). When set on an EU site, items with null sellerType (e.g. sponsored cards) are excluded."},"required":false,"name":"sellerType","in":"query"}],"responses":{"200":{"description":"Sold listings","content":{"application/json":{"schema":{"type":"object","properties":{"keyword":{"type":"string"},"page":{"type":"number","description":"Page number that was fetched"},"totalItems":{"type":"number","description":"Number of items returned on this page"},"hasNextPage":{"type":"boolean","description":"Whether more pages are available"},"autoSelectedCategory":{"type":"object","nullable":true,"properties":{"id":{"type":"string","example":"9355"},"name":{"type":"string","example":"Cell Phones & Smartphones"}},"required":["id","name"],"description":"Category auto-selected by eBay for this search. Present when eBay narrows a categoryId=0 search to a specific category. null when no auto-selection occurs or when a specific categoryId was requested."},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"256123456789"},"url":{"type":"string","example":"https://www.ebay.com/itm/256123456789?nordt=true"},"thumbnailUrl":{"type":"string","nullable":true,"description":"URL of the listing thumbnail image from the eBay search results page (500px). Hosted on i.ebayimg.com. null when no product image is available.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp"},"fullResThumbnailUrl":{"type":"string","nullable":true,"description":"Full-resolution version of thumbnailUrl (~1600px). Derived by replacing the size suffix (s-l500, s-l140, etc.) with s-l1600. The eBay CDN returns the highest available resolution up to 1600px. null when thumbnailUrl is null.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp"},"epid":{"type":"string","nullable":true,"description":"eBay catalog product ID (epid) when the listing is matched to a product in eBay's catalog. Stable across sellers for the same product variant — useful for grouping comps. null when the listing has no catalog match.","example":"20049285656"},"title":{"type":"string","nullable":true,"example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"condition":{"type":"string","nullable":true,"description":"Item condition label as displayed on eBay (localized per site). e.g. \"Pre-Owned\", \"Gebraucht\", \"Brand New\", \"Nur Ersatzteile\". Labels vary by eBay site language and category. null when the listing has no condition listed. See https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html for the full condition taxonomy.","example":"Pre-Owned"},"conditionId":{"type":"integer","nullable":true,"description":"eBay numeric condition ID resolved from the condition label via best-effort lookup. null when the label is unrecognized. Common IDs: 1000 (New), 1500 (Open box / New Other), 2000-2030 (Refurbished tiers), 3000 (Used / Pre-Owned), 7000 (For parts). Full reference: https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html","example":3000},"sellerType":{"type":"string","nullable":true,"enum":["private","business"],"description":"Seller type on EU eBay sites (ebay.de, .fr, .it, .es): \"private\" for individual sellers, \"business\" for commercial/professional sellers. null on non-EU sites (ebay.com, .co.uk, .ca, .com.au) where eBay does not surface this data on search results.","example":"private"},"buyingFormat":{"type":"string","nullable":true,"enum":["auction","buyItNow","auctionWithBIN"],"description":"How the item was listed. \"auction\" = competitive bidding only, \"buyItNow\" = fixed price (includes Best Offer listings), \"auctionWithBIN\" = auction that also had a Buy It Now option. null when the listing type could not be determined from the search result.","example":"auction"},"bestOfferAccepted":{"type":"boolean","description":"When true, the seller accepted a best offer below the original asking price. soldPrice is the actual accepted amount; the original asking price was higher (visible as a strikethrough on eBay but not exposed in this API). Detected when a listing shows \"or Best Offer\" text AND a strikethrough original price.","example":false},"bidCount":{"type":"integer","nullable":true,"description":"Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.","example":12},"categoryId":{"type":"string","example":"9355"},"endedAt":{"type":"string","description":"ISO 8601 sold date","example":"2026-03-10T18:42:00.000Z"},"soldPrice":{"type":"string","nullable":true,"example":"899.99"},"soldCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingPrice":{"type":"string","nullable":true,"example":"0.00"},"shippingCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingType":{"type":"string","nullable":true,"enum":["free","paid","pickup","unknown"]},"totalPrice":{"type":"string","nullable":true,"example":"899.99"},"sellerUsername":{"type":"string","nullable":true,"example":"top-deals-store"},"sellerPositivePercent":{"type":"number","nullable":true,"example":99.8},"sellerFeedbackScore":{"type":"number","nullable":true,"example":14200},"itemLocation":{"type":"string","nullable":true,"description":"Seller location country as shown on the eBay search results page. Localized per eBay site language (e.g., \"United States\" on ebay.com, \"Großbritannien\" on ebay.de, \"Stati Uniti\" on ebay.it). null when eBay does not display location (always null on ebay.co.uk, and omitted on some listings across other sites).","example":"United States"},"scrapedAt":{"type":"string","example":"2026-03-14T21:00:00.000Z"}},"required":["itemId","url","thumbnailUrl","fullResThumbnailUrl","epid","title","condition","conditionId","sellerType","buyingFormat","bestOfferAccepted","bidCount","categoryId","endedAt","soldPrice","soldCurrency","shippingPrice","shippingCurrency","shippingType","totalPrice","sellerUsername","sellerPositivePercent","sellerFeedbackScore","itemLocation","scrapedAt"]}}},"required":["keyword","page","totalItems","hasNextPage","autoSelectedCategory","items"]}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"401":{"description":"Request did not originate from RapidAPI","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Scrape failed (eBay connectivity or proxy issue)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}},"502":{"description":"eBay served a bot challenge that all fetch layers failed to bypass","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"detail":{"type":"string"}},"required":["error"]}}}}}}},"/send-export":{"post":{"tags":["Export"],"summary":"Send sold listings export via email","description":"Generates an Excel file from the provided sold listings and emails it to the specified address via Mailgun.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"keyword":{"type":"string","minLength":1,"maxLength":200},"items":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","nullable":true},"soldPrice":{"type":"string","nullable":true},"totalPrice":{"type":"string","nullable":true},"shippingPrice":{"type":"string","nullable":true},"soldCurrency":{"type":"string","nullable":true},"endedAt":{"type":"string"},"sellerUsername":{"type":"string","nullable":true},"url":{"type":"string"},"itemId":{"type":"string"},"categoryId":{"type":"string"},"sellerPositivePercent":{"type":"number","nullable":true},"sellerFeedbackScore":{"type":"number","nullable":true},"shippingType":{"type":"string","nullable":true},"scrapedAt":{"type":"string"}},"required":["title","soldPrice","totalPrice","endedAt"]},"minItems":1,"maxItems":240}},"required":["email","keyword","items"]}}}},"responses":{"200":{"description":"Email queued for delivery","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"}},"required":["success"]}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"500":{"description":"Email send failed","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}}}}},"/api/bulk-search":{"post":{"tags":["Direct Access"],"summary":"Bulk search eBay sold listings (SSE stream)","description":"Accepts 1–20 keywords and streams results back in real time via Server-Sent Events (SSE). Each keyword runs as a separate eBay search and consumes 1 quota request on success. Failed keywords do not consume quota. Keywords are processed in batches of 3 in parallel — results stream as each keyword completes within a batch, and the next batch starts once the current batch finishes.\n\n**SSE event types:**\n- `progress` — keyword started scraping\n- `result` — keyword completed, includes items array\n- `error` — keyword failed (quota not charged)\n- `complete` — all keywords done, stream closes\n\nQuota is reserved atomically upfront. If some (but not all) keywords fit in your remaining quota, the ones that fit are processed and the rest are returned as `error` events with reason `quota exhausted`. If none fit, the request is rejected with 429 before any scraping starts.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keywords":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":20,"description":"Search keywords (1–20). Each keyword is one quota request.","example":["rtx 4080","rtx 4090"]},"count":{"type":"integer","minimum":1,"maximum":240,"default":240,"example":240},"ebaySite":{"type":"string","enum":["ebay.com","ebay.co.uk","ebay.de","ebay.fr","ebay.it","ebay.es","ebay.ca","ebay.com.au"],"default":"ebay.com","example":"ebay.com"},"sortOrder":{"type":"string","enum":["endedRecently","timeNewlyListed","pricePlusPostageLowest","pricePlusPostageHighest","distanceNearest"],"default":"endedRecently"},"itemCondition":{"type":"string","enum":["any","new","used"],"default":"any"},"minPrice":{"type":"number","minimum":0,"example":100},"maxPrice":{"type":"number","minimum":0,"example":800}},"required":["keywords"]}}}},"responses":{"200":{"description":"SSE stream of per-keyword progress, results, errors, and a final summary","content":{"text/event-stream":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["progress","result","error","complete"],"description":"SSE event type"},"data":{"anyOf":[{"type":"object","properties":{"keyword":{"type":"string"},"status":{"type":"string","enum":["processing"]}},"required":["keyword","status"]},{"type":"object","properties":{"keyword":{"type":"string"},"status":{"type":"string","enum":["completed"]},"totalItems":{"type":"number"},"hasNextPage":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"itemId":{"type":"string","example":"256123456789"},"url":{"type":"string","example":"https://www.ebay.com/itm/256123456789?nordt=true"},"thumbnailUrl":{"type":"string","nullable":true,"description":"URL of the listing thumbnail image from the eBay search results page (500px). Hosted on i.ebayimg.com. null when no product image is available.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp"},"fullResThumbnailUrl":{"type":"string","nullable":true,"description":"Full-resolution version of thumbnailUrl (~1600px). Derived by replacing the size suffix (s-l500, s-l140, etc.) with s-l1600. The eBay CDN returns the highest available resolution up to 1600px. null when thumbnailUrl is null.","example":"https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp"},"epid":{"type":"string","nullable":true,"description":"eBay catalog product ID (epid) when the listing is matched to a product in eBay's catalog. Stable across sellers for the same product variant — useful for grouping comps. null when the listing has no catalog match.","example":"20049285656"},"title":{"type":"string","nullable":true,"example":"Apple iPhone 15 Pro 256GB Natural Titanium"},"condition":{"type":"string","nullable":true,"description":"Item condition label as displayed on eBay (localized per site). e.g. \"Pre-Owned\", \"Gebraucht\", \"Brand New\", \"Nur Ersatzteile\". Labels vary by eBay site language and category. null when the listing has no condition listed. See https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html for the full condition taxonomy.","example":"Pre-Owned"},"conditionId":{"type":"integer","nullable":true,"description":"eBay numeric condition ID resolved from the condition label via best-effort lookup. null when the label is unrecognized. Common IDs: 1000 (New), 1500 (Open box / New Other), 2000-2030 (Refurbished tiers), 3000 (Used / Pre-Owned), 7000 (For parts). Full reference: https://developer.ebay.com/api-docs/sell/static/metadata/condition-id-values.html","example":3000},"sellerType":{"type":"string","nullable":true,"enum":["private","business"],"description":"Seller type on EU eBay sites (ebay.de, .fr, .it, .es): \"private\" for individual sellers, \"business\" for commercial/professional sellers. null on non-EU sites (ebay.com, .co.uk, .ca, .com.au) where eBay does not surface this data on search results.","example":"private"},"buyingFormat":{"type":"string","nullable":true,"enum":["auction","buyItNow","auctionWithBIN"],"description":"How the item was listed. \"auction\" = competitive bidding only, \"buyItNow\" = fixed price (includes Best Offer listings), \"auctionWithBIN\" = auction that also had a Buy It Now option. null when the listing type could not be determined from the search result.","example":"auction"},"bestOfferAccepted":{"type":"boolean","description":"When true, the seller accepted a best offer below the original asking price. soldPrice is the actual accepted amount; the original asking price was higher (visible as a strikethrough on eBay but not exposed in this API). Detected when a listing shows \"or Best Offer\" text AND a strikethrough original price.","example":false},"bidCount":{"type":"integer","nullable":true,"description":"Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.","example":12},"categoryId":{"type":"string","example":"9355"},"endedAt":{"type":"string","description":"ISO 8601 sold date","example":"2026-03-10T18:42:00.000Z"},"soldPrice":{"type":"string","nullable":true,"example":"899.99"},"soldCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingPrice":{"type":"string","nullable":true,"example":"0.00"},"shippingCurrency":{"type":"string","nullable":true,"example":"USD"},"shippingType":{"type":"string","nullable":true,"enum":["free","paid","pickup","unknown"]},"totalPrice":{"type":"string","nullable":true,"example":"899.99"},"sellerUsername":{"type":"string","nullable":true,"example":"top-deals-store"},"sellerPositivePercent":{"type":"number","nullable":true,"example":99.8},"sellerFeedbackScore":{"type":"number","nullable":true,"example":14200},"itemLocation":{"type":"string","nullable":true,"description":"Seller location country as shown on the eBay search results page. Localized per eBay site language (e.g., \"United States\" on ebay.com, \"Großbritannien\" on ebay.de, \"Stati Uniti\" on ebay.it). null when eBay does not display location (always null on ebay.co.uk, and omitted on some listings across other sites).","example":"United States"},"scrapedAt":{"type":"string","example":"2026-03-14T21:00:00.000Z"}},"required":["itemId","url","thumbnailUrl","fullResThumbnailUrl","epid","title","condition","conditionId","sellerType","buyingFormat","bestOfferAccepted","bidCount","categoryId","endedAt","soldPrice","soldCurrency","shippingPrice","shippingCurrency","shippingType","totalPrice","sellerUsername","sellerPositivePercent","sellerFeedbackScore","itemLocation","scrapedAt"]}}},"required":["keyword","status","totalItems","hasNextPage","items"]},{"type":"object","properties":{"keyword":{"type":"string"},"status":{"type":"string","enum":["failed"]},"error":{"type":"string"}},"required":["keyword","status","error"]},{"type":"object","properties":{"total":{"type":"number"},"succeeded":{"type":"number"},"failed":{"type":"number"}},"required":["total","succeeded","failed"]}],"description":"Event payload (varies by event type)"}},"required":["event","data"]}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"details":{"nullable":true}},"required":["error"]}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]}}}},"429":{"description":"Insufficient quota — not enough remaining requests for all keywords","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"plan":{"type":"string"},"limit":{"type":"number"},"used":{"type":"number"},"remaining":{"type":"number"},"needed":{"type":"number"}},"required":["error","plan","limit","used","remaining","needed"]}}}}}}}}}