API reference
eBay sold listings, as JSON
One authenticated GET: a search with every filter the dashboard has, and the sold listings that match, newest first, 100 a page, each with the listing page behind it: every item specific, the description, the images, the seller, and the price actually paid. Ask for up to ten pages at once. Each page is one credit. The averages, trends and breakdowns live on the dashboard; the API is for the listings. Available on the Professional plan.
Quickstart
On a Professional plan, create a key under API, or try a request in its playground first. Then:
curl
curl "https://api.soldpeak.com/ebay/v1/sold?q=nintendo+switch+oled&lookback=90d&condition=used&pages=2" \ -H "Authorization: Bearer YOUR_API_KEY"Authentication
Send your key in the Authorization header as a bearer token. The X-Api-Key header works too.
Authorization: Bearer sp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxKeys are shown once, at creation, and can be revoked instantly. A revoked or unknown key gets a 401. Keep keys server-side.
The endpoint
GET https://api.soldpeak.com/ebay/v1/soldReads the index directly and answers in well under a second: the sales that match your search and filters, newest first, from page for pages pages. Each page returned is one credit from the same daily limit as the dashboard. The same call again from your account within six hours is not counted again, up to 20 times; the 21st is counted and starts another 20. /research still answers, with the same response.
Parameters
| Name | Type | Description |
|---|---|---|
| q | string | Keywords. Every word must appear in the listing title, in any order. Required unless category is set. |
| marketplace | US | UKdefault US | Which eBay site to research. Prices come back in that site's currency. |
| lookback | 7d | 30d | 90d | all | customdefault 90d | How far back to look. all is every sale since 2026-07-25, when the data starts (Professional). With custom, send date_from and date_to; the span can be as long as your plan's history. |
| date_from | YYYY-MM-DD | Start of a custom window, inclusive. The data starts 2026-07-25 for now; an earlier date is moved up to it. |
| date_to | YYYY-MM-DD | End of a custom window, inclusive. |
| condition | string | One or more of new, used, parts, other, comma-separated. |
| format | fixed | auction | offer | Only Buy It Now sales, only auctions, or only listings that took best offers. |
| min_price | number | Lowest sold price to include. |
| max_price | number | Highest sold price to include. |
| category | string | An eBay category id to restrict to, leaf or parent (a parent covers every category inside it). Ids differ between the US and UK sites. With no q, researches the whole category. |
| exclude | string | Words that must not appear in the title, comma-separated (or in the description either, with exclude_in). |
| search_in | title | title_descriptiondefault title | Where the keywords must appear. title_description matches a listing whose title or description carries every word. |
| exclude_in | title | title_descriptiondefault title | Where the excluded words must not appear. title_description drops a listing that mentions them anywhere. |
| exclude_sellers | string | eBay usernames whose sales to leave out, comma-separated (up to 20). Leave your own sales out of your comps. |
| exclude_category | string | An eBay category id, leaf or parent, whose sales to leave out (accessories, lots, parts). |
| specifics | string | Item specifics the listing must carry, as Key:Value pairs separated by commas (Brand:Apple,Storage Capacity:256 GB). |
| location | string | Only sales shipped from a location containing this text ("United States", "United Kingdom", "China"). |
| seller | string | Only sales by this eBay username. |
| min_feedback | number | Only sales by sellers with at least this many feedback ratings (min_feedback=20). |
| min_rating | number | Only sales by sellers with at least this positive-feedback percentage (min_rating=98). |
| flags | string | Flags the listing must carry, comma-separated: top_rated (Top Rated seller), free_returns, store (seller has an eBay store), free_shipping, marked_down (sold below a stated list price), single (one item, no variations). |
| max_shipping | number | Only sales whose shipping cost this much or less (max_shipping=5; 0 is free shipping only). |
| min_bids | number | Only auctions that drew at least this many bids (min_bids=5). Implies format=auction. |
| epid | string | Only sales of this eBay catalog product (the ePID on a listing). Can stand alone, without q, to research one product exactly; the hot-on-eBay board links here. |
| page | numberdefault 1 | Which page of sold listings to return, 100 to a page, newest first, through the most recent 15,000 sales. Every page is one credit against your daily limit. |
| pages | numberdefault 1 | How many pages to return in one call, from page onward, up to 10 (a thousand sales). Each page returned is one credit, so pages=10 costs ten. Refused when fewer credits than that are left today. |
Response
200 OK · abridged
{ "query": "nintendo switch oled", "marketplace": "US", "currency": "USD", "coverage": { "from": "2026-07-28", "to": "2026-10-26", "days": 91 }, "total_sold": 9361, "listings": [ { "item_id": "257793876112", "title": "Nintendo Switch OLED Model White Console w/ Dock", "price": 156.0, "shipping": 16.0, "total": 172.0, "date": "2026-10-12T21:16:00.000Z", "condition": "used", "condition_detail": "Pre-Owned", "format": "fixed", "bids": null, "best_offer": false, "location": "United States", "seller": "gamestop", "category_id": "139971", "category": "Video Game Consoles", "url": "https://www.ebay.com/itm/257793876112", "image": "https://i.ebayimg.com/images/g/.../s-l225.jpg", "specifics": [ { "key": "Brand", "value": "Nintendo" }, { "key": "Model", "value": "Nintendo switch oled" }, { "key": "Storage Capacity", "value": "64 gb" } ], "details": { "sale_price": 156.0, "best_offer_accepted": false, "condition_raw": "Pre-Owned", "grading": null, "attributes": [ { "key": "Brand", "value": "Nintendo" }, { "key": "Model", "value": "Nintendo Switch OLED" }, { "key": "Storage Capacity", "value": "64 GB" } ], "images": [ "https://i.ebayimg.com/images/g/.../s-l1600.jpg" ], "description_text": "Works great, light wear on the dock…", "seller": { "username": "gamestop", "feedback_percent": 99.6, "feedback_count": 1203419, "items_sold": 5400000 }, "…": "…" } } ], "with_details": 198, "listings_page": { "page": 1, "pages_returned": 2, "per_page": 100, "pages": 94, "total": 9361 }, "took_ms": 61, "generated_at": "2026-10-26T20:30:00.000Z", "usage": { "used": 12, "limit": 500, "resets_at": "2026-10-27T00:00:00.000Z" }}| Field | Meaning |
|---|---|
| coverage | The window searched, inclusive, and its length in days. The data starts 2026-07-25. |
| total_sold | Every matching sale in the window, whether or not you page through them. |
| listings | The sales, newest first: item_id, title, price, shipping, total, date, condition, condition_detail, format (fixed, auction, offer), bids, best_offer, location, seller, category_id, category, url, image, specifics, and details. |
| listings[].specifics | The item specifics on record for the sale, as key and value pairs, from the search index. Present on every enriched sale whether or not its page is on record. |
| listings[].details | The listing page behind the sale, or null when it was never read: title, condition and condition_raw, condition_description, grading (grader and grade for graded items), listing_state, sold_at, last_updated, sale_price (the amount paid where eBay prints it, which is how accepted offers on cards show their real price), currency, buying_format, bids, best_offer_available, best_offer_accepted, shipping_service, returns_text, seller_accepts_returns, location, location_country, epid, categoryId, images, attributes (every item specific as key and value), description_url, description_text, and seller (username, feedback_percent, feedback_count, items_sold, store). |
| with_details | How many of the returned listings carry a page record. Most recent sales have theirs within minutes; older history often does not. |
| listings_page | page is the first page in listings and pages_returned how many it holds; per_page is 100; pages and total are how far you can page, through the most recent 15,000 sales. |
| usage | Credits used today against your plan's daily limit, and when it resets. |
Credits & limits
- A credit a page.
pages=1is one credit,pages=10is ten. A page past the last one comes back empty and is not counted. A call for more pages than you have credits left today is refused with a429rather than answered in part. - Depth. You can page through the most recent 15,000 sales of a search. For more, narrow the dates: a custom window of a week or a month reaches everything inside it.
- Credits. Professional includes 15,000 API credits a month, with no daily limit and separate from the plan's 500 daily dashboard searches. A tier (below) adds credits on top. Every response carries
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Resetfor the period's pool. The same call again inside six hours is free, up to 20 times. - Rate. One request a second, or the tier's rate. A faster call gets a
429witherror: rate_limitedand aRetry-Afterheader. - Lookback and marketplaces follow your plan: Professional reaches back to 2026-07-25 on eBay.com and eBay.co.uk.
API tiers
A second subscription beside the Professional plan, billed monthly, for volume: each tier adds its credits to the 15,000 the plan includes. No daily limit; the plan's 500 daily searches stay for the dashboard and are never drawn on. Each credit is one page of 100 sold listings. Chosen on the dashboard's API page.
| Tier | A month | Credits added | Listings | Rate |
|---|---|---|---|---|
| API 60k | $100 | 60,000 | 6,000,000 | 1/s |
| API 200k | $250 | 200,000 | 20,000,000 | 10/s |
| API 400k | $500 | 400,000 | 40,000,000 | 10/s |
| API 600k | $750 | 600,000 | 60,000,000 | 10/s |
| API 800k | $1000 | 800,000 | 80,000,000 | 10/s |
| API 1M | $1250 | 1,000,000 | 100,000,000 | 10/s |
Errors
| Status | error | When |
|---|---|---|
| 400 | bad_request | A parameter is missing or malformed. The message says which. |
| 401 | unauthorized | No key, or a key that is invalid or revoked. |
| 403 | plan_limit | The lookback, marketplace or API access itself is beyond the plan. |
| 429 | quota_exceeded | Today's limit is reached. usage.resets_at says when. |
| 502 / 503 | source_error | The index didn't answer in time. Retry with backoff; nothing was counted. |
429
{ "error": "quota_exceeded", "message": "You've used the Professional plan's 500 searches for today. The limit resets at midnight UTC.", "usage": { "used": 500, "limit": 500, "resets_at": "2026-10-14T00:00:00.000Z" } }Examples
JavaScript
javascript
const res = await fetch( "https://api.soldpeak.com/ebay/v1/sold?" + new URLSearchParams({ q: "rolex datejust 36", lookback: "30d", marketplace: "US", pages: "3" }), { headers: { Authorization: "Bearer " + process.env.SOLDPEAK_KEY } });const { total_sold, listings, listings_page } = await res.json();console.log(total_sold, listings.length, listings_page);Python
python
import os, requests r = requests.get( "https://api.soldpeak.com/ebay/v1/sold", params={"q": "charizard psa 10", "lookback": "90d", "format": "fixed", "page": 1, "pages": 5}, headers={"Authorization": f"Bearer {os.environ['SOLDPEAK_KEY']}"},)data = r.json()for sale in data["listings"]: print(sale["date"][:10], sale["price"], sale["title"])Help
Stuck, or need a field we don't return yet? Get in touch or email [email protected].