API documentation

A single bearer-authenticated REST API for completed eBay sales. One call returns up to 240 sales for a keyword as JSON, with full listing detail, across eight marketplaces. Batch jobs, active listings, and CSV export are included.

Authentication

Create an API key in your dashboard and send it as a bearer token on every request. Keep it server side.

Base URL   https://api.ebaysoldlistingsapi.com
Header     Authorization: Bearer YOUR_API_KEY

Quickstart

Search completed sales for a keyword. The same request works from any language.

cURL

curl "https://api.ebaysoldlistingsapi.com/scrape?keyword=nintendo+switch+oled" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.ebaysoldlistingsapi.com/scrape?keyword=nintendo+switch+oled",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.results);

Python

import requests

r = requests.get(
    "https://api.ebaysoldlistingsapi.com/scrape",
    params={"keyword": "nintendo switch oled"},
    headers={"Authorization": "Bearer YOUR_API_KEY"},
)
print(r.json()["results"])

Sold search

The core endpoint. Returns completed sales for a keyword on one marketplace.

GET/scrape

Parameters

keywordstringrequired

The search term, exactly as you would type it on eBay, up to 300 characters. URL-encode spaces.

ebaySitestringoptional

Marketplace to search. Defaults to ebay.com. See the marketplace list below.

countintegeroptional

Number of results, 1 to 240. Defaults to 240.

pageintegeroptional

Page of results, 1 to 100, for paging beyond the first response.

soldbooleanoptional

Defaults to true (completed sales). Set to false to return current active listings instead.

sortOrderstringoptional

One of endedRecently, timeNewlyListed, pricePlusPostageLowest, pricePlusPostageHighest, distanceNearest.

itemConditionstringoptional

Filter by condition: any, new, or used. For a precise eBay condition, pass conditionId.

buyingFormatstringoptional

all, auction, buyItNow, or acceptsOffers.

minPrice / maxPricenumberoptional

Restrict results to a price band, in the marketplace currency.

soldAfter / soldBeforedateoptional

Restrict completed sales to a date range, format YYYY-MM-DD.

itemLocationstringoptional

default, domestic, or worldwide.

categoryIdstringoptional

Restrict to an eBay category by numeric id.

Response

Every response returns the complete set of matching sales, each with full listing detail in the marketplace's own currency, ready to drop straight into your database, model, or spreadsheet.

{
  "keyword": "nintendo switch oled",
  "ebaySite": "ebay.com",
  "count": 240,
  "results": [
    {
      "itemId": "1256xxxxxxxx",
      "title": "Nintendo Switch OLED White",
      "soldPrice": "255.00",
      "currency": "USD",
      "soldDate": "2026-09-20",
      "condition": "Used",
      "buyingFormat": "Fixed price",
      "bids": null,
      "shipping": "Free",
      "seller": "top_deals_88",
      "itemUrl": "https://www.ebay.com/itm/1256xxxxxxxx",
      "image": "https://i.ebayimg.com/images/g/..."
    }
  ]
}

Result fields

titlestringoptional

The listing title as it appeared on eBay.

soldPricestringoptional

Final sale price, as a decimal string.

currencystringoptional

ISO currency code for the price (USD, GBP, EUR, AUD, CAD).

soldDatestringoptional

Date the sale completed, format YYYY-MM-DD.

conditionstringoptional

The item condition eBay recorded for the listing.

buyingFormatstringoptional

Fixed price or Auction; auctions also include a bid count.

shippingstringoptional

Shipping cost or Free.

sellerstringoptional

The seller username.

itemUrlstringoptional

Direct link to the eBay listing.

imagestringoptional

URL of the primary listing image.

Active listings

Set sold=false on the same endpoint to return current live listings in the same shape, useful for comparing what is selling against what is on the market right now.

curl "https://api.ebaysoldlistingsapi.com/scrape?keyword=nintendo+switch+oled&sold=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

Batch jobs

Process many keywords in one asynchronous job instead of firing hundreds of calls. Submit a job, poll it, then read the combined results. One batch runs per account at a time.

POST/scrape/batch

curl -X POST "https://api.ebaysoldlistingsapi.com/scrape/batch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keywords": ["nintendo switch oled", "steam deck 512gb", "ps5 slim"],
    "ebaySite": "ebay.com",
    "count": 240
  }'

Returns a job id to poll:

{ "jobId": "job_9f2c...", "status": "queued", "resultsUrl": "/scrape/batch/job_9f2c..." }

Poll the job

GET/scrape/batch/{jobId}

{
  "jobId": "job_9f2c...",
  "status": "complete",
  "completed": 3,
  "total": 3,
  "results": [
    { "keyword": "nintendo switch oled", "results": [ /* sales */ ] },
    { "keyword": "steam deck 512gb",     "results": [ /* sales */ ] },
    { "keyword": "ps5 slim",             "results": [ /* sales */ ] }
  ]
}

status moves through queued → running → complete. Each keyword still counts as one request against your allowance.

CSV export

Any sold search or completed batch can come back as CSV instead of JSON, one row per sale, ready for a spreadsheet.

# a single search as CSV
curl "https://api.ebaysoldlistingsapi.com/scrape?keyword=steam+deck&format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

# a finished batch job as CSV
curl "https://api.ebaysoldlistingsapi.com/scrape/batch/job_9f2c.../download.csv" \
  -H "Authorization: Bearer YOUR_API_KEY"

Account & usage

Check your plan and how much of your monthly allowance is left.

GET/account/usage

{
  "plan": "growth",
  "quota": 15000,
  "used": 4200,
  "remaining": 10800,
  "resetsAt": "2026-10-01T00:00:00Z"
}

Marketplaces

Pass any of these as ebaySite. Prices return in each site's local currency.

ebay.com      United States   USD
ebay.co.uk    United Kingdom  GBP
ebay.de       Germany         EUR
ebay.com.au   Australia       AUD
ebay.ca       Canada          CAD
ebay.fr       France          EUR
ebay.it       Italy           EUR
ebay.es       Spain           EUR

Rate limits

Each plan has a per-second rate limit and a monthly request allowance. Exceed the per-second limit and you get an HTTP 429 with a Retry-After header, so back off and retry. Every response also carries X-RateLimit-Remaining. For large catalogs, use batch jobs rather than pushing the rate. See pricing for per-plan limits.

Errors

Errors return an HTTP status and a JSON body with a stable code and a readable message.

{ "error": "Too many requests, slow down.", "code": "rate_limited" }

400  invalid_params    a parameter is missing or invalid
401  unauthorized      missing or invalid API key
402  quota_exceeded    monthly allowance used up
403  forbidden         key lacks scope for this endpoint
409  conflict          a batch job is already running
429  rate_limited      per-second limit hit, see Retry-After
502  upstream_error    could not reach eBay, retry shortly