SoldCompsdocs

API Reference · v1

SoldComps API

Real eBay completed sales — price, condition, date, seller — from a single request. No scraping setup, no stale cache, no OAuth dance. Three endpoints: synchronous /v1/scrape for one page at a time, async Max Mode for server-side pagination, and a RapidAPI marketplace channel.

Machine-readable spec: openapi.json

New to eBay sold data? See how we compare →

Quickstart

curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&count=10"

Authentication

All /v1/scrape and Max Mode requests require a bearer token:

Authorization: Bearer sc_YOUR_KEY_HERE

API keys start with sc_. Get one from the dashboard. The free plan includes 100 requests/month, no credit card required.

The /rapidapi/scrape-ebay endpoint authenticates through the RapidAPI marketplace headers instead — see the RapidAPI section.

Rate limits

Every plan shares a uniform 60 requests/minute per-key rate limit. When exceeded the API returns 429 with a Retry-After header.

Monthly request quotas vary by plan and are enforced separately from the per-minute bucket. When exhausted the API returns 403 until your billing cycle rolls. See current plan limits at /dashboard/subscription.

Errors

StatusMeaningWhat to do
400Invalid paramsCheck the error body — usually a missing keyword or out-of-range number.
401Missing or invalid API keyVerify the Authorization header. Keys start with sc_.
403Monthly quota exhaustedUpgrade or wait until the next billing cycle. Resets follow your subscription anchor, not calendar UTC.
429Per-minute rate limitBack off for the duration in Retry-After. Limits are 60/min on every plan.
502Upstream blockedeBay blocked the request. Retry; transient.
500Server errorUnexpected internal error. Retry with exponential backoff.

Pagination

Each /v1/scrape request returns one page of up to 240 sold listings. Increment the page parameter until hasNextPage is false.

Running the pagination loop client-side is fine for small sweeps. For larger jobs (50+ pages), use Max Mode instead — the server paginates, handles retries, and delivers results inline, via email, or as a signed CSV.

totalItems in the response is the count of items returned on the current page, not a grand total.

# Increment page until hasNextPage is false
curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape?keyword=iphone+15+pro&page=1"
# then page=2, page=3, ... while hasNextPage == true
GET/v1/scrape

Search sold listings

One keyword search returns up to 240 real completed eBay sales. Filters narrow by site, category, date window, price range, condition, and seller type.

Query parameters

keywordstringrequired
eBay search term. URL-encode spaces and special characters.
pageintegeroptionaldefault: 1
Page number of eBay results to fetch. Increment until hasNextPage is false.
countinteger (1–240)optionaldefault: 240
Max items per page. Range 1–240 on every plan.
daysToScrapeinteger (1–365)optionaldefault: 30
How far back to look for sold listings, in days.
ebaySiteenumoptionaldefault: ebay.com
eBay domain to scrape.
ebay.comebay.co.ukebay.deebay.frebay.itebay.esebay.caebay.com.au
categoryIdstringoptionaldefault: 0
eBay category ID (_sacat). Browse all 17,000+ IDs at sold-comps.com/ebay-categories. Use "0" for all categories.
sortOrderenumoptionaldefault: endedRecently
Sort order for results.
endedRecentlytimeNewlyListedpricePlusPostageLowestpricePlusPostageHighestdistanceNearest
minPricenumberoptional
Minimum price filter, in listing currency.
maxPricenumberoptional
Maximum price filter, in listing currency.
itemLocationenumoptionaldefault: default
Item location filter.
defaultdomesticworldwide
itemConditionenumoptionaldefault: any
Item condition filter applied as a request filter on eBay.
anynewused
sellerTypeenumoptional
Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). On non-EU sites the filter is silently ignored.
privatebusiness

Response fields (each item)

itemIdstringoptional
eBay listing item ID.
urlstringoptional
Canonical listing URL with ?nordt=true to bypass eBay's catalog redirect.
thumbnailUrlstring | nulloptional
Listing thumbnail (500px) from i.ebayimg.com. null when the listing has no product image.
epidstring | nulloptional
eBay catalog product ID. Stable across sellers for the same variant. null when the listing has no catalog match.
titlestring | nulloptional
Listing title.
conditionstring | nulloptional
Localized display label (e.g. "Pre-Owned", "Gebraucht"). Authoritative — what the buyer saw.
conditionIdnumber | nulloptional
eBay numeric condition ID (best-effort lookup from the localized label). Common: 1000 New, 3000 Used, 7000 For parts.
sellerType"private" | "business" | nulloptional
EU sites only (ebay.de, .fr, .it, .es). null on all non-EU sites.
buyingFormat"auction" | "buyItNow" | "auctionWithBIN" | nulloptional
How the item was listed. "auction" = competitive bidding, "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.
bestOfferAcceptedbooleanoptional
true when the seller accepted a best offer. soldPrice is the actual accepted amount; the original asking price (higher) was visible as a strikethrough on eBay. Detected from strikethrough + "or Best Offer" signals on the search card.
bidCountnumber | nulloptional
Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.
categoryIdstringoptional
eBay category ID.
endedAtstringoptional
ISO 8601 sold/ended date.
soldPricestring | nulloptional
Sold price as a decimal string.
soldCurrencystring | nulloptional
ISO 4217 currency code (e.g. "USD", "GBP").
shippingPricestring | nulloptional
Shipping cost; "0.00" when free, null when unknown.
shippingType"free" | "paid" | "pickup" | "unknown" | nulloptional
Shipping category.
totalPricestring | nulloptional
soldPrice + shippingPrice when both known.
sellerUsernamestring | nulloptional
eBay seller username.
sellerPositivePercentnumber | nulloptional
Seller positive feedback percentage.
sellerFeedbackScorenumber | nulloptional
Seller total feedback count.
itemLocationstring | nulloptional
Seller's country as shown on the eBay search results page. Localized per site language (e.g., "United States" on ebay.com, "Großbritannien" on ebay.de). null on ebay.co.uk and when eBay omits the location for a listing.
scrapedAtstringoptional
ISO 8601 timestamp of when SoldComps fetched the listing.

Request

curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  "https://api.sold-comps.com/v1/scrape\
?keyword=iphone+15+pro\
&ebaySite=ebay.com\
&page=1\
&count=240\
&daysToScrape=30\
&sortOrder=endedRecently"

Response

{
  "keyword": "iphone 15 pro",
  "page": 1,
  "totalItems": 240,
  "hasNextPage": true,
  "autoSelectedCategory": { "id": "9355", "name": "Cell Phones & Smartphones" },
  "items": [
    {
      "itemId": "256123456789",
      "url": "https://www.ebay.com/itm/256123456789?nordt=true",
      "thumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp",
      "fullResThumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp",
      "epid": "20049285656",
      "title": "Apple iPhone 15 Pro 256GB Natural Titanium - Unlocked",
      "condition": "Pre-Owned",
      "conditionId": 3000,
      "sellerType": null,
      "buyingFormat": "buyItNow",
      "bestOfferAccepted": false,
      "bidCount": null,
      "categoryId": "9355",
      "endedAt": "2026-03-10T18:42:00.000Z",
      "soldPrice": "899.99",
      "soldCurrency": "USD",
      "shippingPrice": "0.00",
      "shippingCurrency": "USD",
      "shippingType": "free",
      "totalPrice": "899.99",
      "sellerUsername": "top-deals-store",
      "sellerPositivePercent": 99.8,
      "sellerFeedbackScore": 14200,
      "itemLocation": "United States",
      "scrapedAt": "2026-03-14T21:00:00.000Z"
    }
  ]
}

Async sweeps

Max Mode

Max Mode auto-paginates server-side. Submit once, then poll for progress, get the result by email, or stream a signed CSV. Unlike /v1/scrape, a Max Mode submission is not 1 credit — each successfully scraped page debits 1 request from your monthly quota. A 50-page sweep can cost up to 50 requests. Failed pages don't debit. maxPages caps blast radius (max 100).

One job per user can be active at a time. A second submit while one is running returns 409 with the existing jobId.

POST/v1/scrape/max

Submit

Enqueue an async sweep. Returns a jobId you can poll, cancel, or wait for the worker to deliver via email / signed download URL. Pass Idempotency-Key to dedupe re-submits over a 24h window.

Request body

keywordstringrequired
eBay search term.
maxPagesinteger (1–100)optionaldefault: 50
Upper bound on how many pages the worker will fetch. Each successful page debits 1 request from your monthly quota.
resultTypeenumoptionaldefault: inline
How to deliver the result: inline (poll the results endpoint), email (CSV attached or signed link), download (signed CSV stream URL).
inlineemaildownload
emailTostringoptional
Recipient address when resultType=email. Falls back to the account email on file.
daysToScrapeinteger (1–365)optionaldefault: 90
History window in days.
ebaySiteenumoptionaldefault: ebay.com
eBay domain to scrape.
ebay.comebay.co.ukebay.deebay.frebay.itebay.esebay.caebay.com.au
categoryIdstringoptionaldefault: 0
eBay category ID (_sacat).
sortOrderenumoptionaldefault: endedRecently
Sort order.
endedRecentlytimeNewlyListedpricePlusPostageLowestpricePlusPostageHighestdistanceNearest
minPricenumberoptional
Minimum price filter.
maxPricenumberoptional
Maximum price filter.
itemLocationenumoptionaldefault: default
Item location filter.
defaultdomesticworldwide
itemConditionenumoptionaldefault: any
Item condition filter.
anynewused
sellerTypeenumoptional
EU sites only.
privatebusiness

Request

curl -X POST https://api.sold-comps.com/v1/scrape/max \
  -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rtx-4090-march-sweep" \
  -d '{
    "keyword": "rtx 4090",
    "maxPages": 50,
    "resultType": "email",
    "emailTo": "[email protected]",
    "ebaySite": "ebay.com",
    "daysToScrape": 90
  }'

Response

{
  "jobId": "8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31",
  "status": "queued",
  "resultsUrl": "/v1/scrape/max/results/8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31",
  "estimatedSeconds": 150
}
GET/v1/scrape/max/results/:jobId

Poll

Returns progress while the job is running, or a summary + delivery info once terminal. Recommended poll interval is 5 seconds. The job retains results for 30 days, then 410 Gone.

Terminal statuses: done, failed, cancelled, quota_exhausted, upstream_unhealthy.

terminationReason: natural_end (no more pages), maxPages_reached, quota_exhausted, upstream_unhealthy (5 consecutive page failures), cancelled, or terminal_error (page 1 failed).

Running response

{
  "jobId": "8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31",
  "status": "running",
  "keyword": "rtx 4090",
  "ebaySite": "ebay.com",
  "createdAt": "2026-06-13T20:01:14.000Z",
  "startedAt": "2026-06-13T20:01:14.000Z",
  "progress": {
    "currentPage": 12,
    "pagesAttempted": 12,
    "pagesSucceeded": 12,
    "pagesFailed": 0,
    "failedPages": [],
    "itemsCollected": 2880,
    "consecutiveFailures": 0
  }
}

Request

curl -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  https://api.sold-comps.com/v1/scrape/max/results/8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31

Response

{
  "jobId": "8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31",
  "status": "done",
  "keyword": "rtx 4090",
  "ebaySite": "ebay.com",
  "createdAt": "2026-06-13T20:01:13.000Z",
  "startedAt": "2026-06-13T20:01:14.000Z",
  "completedAt": "2026-06-13T20:04:09.000Z",
  "expiresAt": "2026-07-13T20:04:09.000Z",
  "summary": {
    "pagesAttempted": 42,
    "pagesSucceeded": 42,
    "pagesFailed": 0,
    "failedPages": [],
    "totalItems": 9870,
    "partial": false,
    "terminationReason": "natural_end"
  },
  "error": null,
  "delivery": {
    "method": "email",
    "status": "delivered",
    "lastError": null
  }
}
DELETE/v1/scrape/max/:jobId

Cancel

Marks the job for cancellation. The worker checks between pages, so a job mid-page can take a few seconds to settle. Idempotent — repeat calls return 200. Pages already scraped are not refunded.

Returns 200 with the updated job status. The final delivery for cancelled jobs is short-circuited — no email is sent and the CSV download returns the partial result so far.

Request

curl -X DELETE \
  -H "Authorization: Bearer sc_YOUR_KEY_HERE" \
  https://api.sold-comps.com/v1/scrape/max/8c2f1a3e-3b54-4f6b-9c2a-1d6e2b9a0d31
GET/v1/scrape/max/:jobId/download.csv

Download CSV

Streams the full result as CSV. Authenticated with a signed token in the ?token= query parameter, not a Bearer header — the URL is safe to share in email. Tokens expire 24 hours after the job completes.

The download URL is returned at the top level of the poll response as downloadUrl (when resultType=download) or attached directly to completion emails. Do not append your API key — the signed token is the auth.

CSV columns: every field on the per-item response, one row per listing.

Request

# The download URL is returned in the poll response when
# resultType=download. The token is in the URL — do NOT add a Bearer header.

curl -o results.csv \
  "https://api.sold-comps.com/v1/scrape/max/8c2f1a3e.../download.csv?token=eyJhb..."
GET/rapidapi/scrape-ebay

RapidAPI - Scrape eBay

Identical response shape to /v1/scrape, but callable only through the SoldComps RapidAPI listing. Auth is via RapidAPI's marketplace headers — X-RapidAPI-Key + X-RapidAPI-Host — not Bearer tokens. Quotas and billing run through your RapidAPI subscription.

Query parameters

keywordstringrequired
eBay search term. URL-encode spaces and special characters.
pageintegeroptionaldefault: 1
Page number of eBay results to fetch. Increment until hasNextPage is false.
countinteger (1–240)optionaldefault: 240
Max items per page. Range 1–240 on every plan.
daysToScrapeinteger (1–365)optionaldefault: 30
How far back to look for sold listings, in days.
ebaySiteenumoptionaldefault: ebay.com
eBay domain to scrape.
ebay.comebay.co.ukebay.deebay.frebay.itebay.esebay.caebay.com.au
categoryIdstringoptionaldefault: 0
eBay category ID (_sacat). Browse all 17,000+ IDs at sold-comps.com/ebay-categories. Use "0" for all categories.
sortOrderenumoptionaldefault: endedRecently
Sort order for results.
endedRecentlytimeNewlyListedpricePlusPostageLowestpricePlusPostageHighestdistanceNearest
minPricenumberoptional
Minimum price filter, in listing currency.
maxPricenumberoptional
Maximum price filter, in listing currency.
itemLocationenumoptionaldefault: default
Item location filter.
defaultdomesticworldwide
itemConditionenumoptionaldefault: any
Item condition filter applied as a request filter on eBay.
anynewused
sellerTypeenumoptional
Filter results by seller type. Only effective on EU sites (ebay.de, .fr, .it, .es). On non-EU sites the filter is silently ignored.
privatebusiness

Response fields (each item)

itemIdstringoptional
eBay listing item ID.
urlstringoptional
Canonical listing URL with ?nordt=true to bypass eBay's catalog redirect.
thumbnailUrlstring | nulloptional
Listing thumbnail (500px) from i.ebayimg.com. null when the listing has no product image.
epidstring | nulloptional
eBay catalog product ID. Stable across sellers for the same variant. null when the listing has no catalog match.
titlestring | nulloptional
Listing title.
conditionstring | nulloptional
Localized display label (e.g. "Pre-Owned", "Gebraucht"). Authoritative — what the buyer saw.
conditionIdnumber | nulloptional
eBay numeric condition ID (best-effort lookup from the localized label). Common: 1000 New, 3000 Used, 7000 For parts.
sellerType"private" | "business" | nulloptional
EU sites only (ebay.de, .fr, .it, .es). null on all non-EU sites.
buyingFormat"auction" | "buyItNow" | "auctionWithBIN" | nulloptional
How the item was listed. "auction" = competitive bidding, "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.
bestOfferAcceptedbooleanoptional
true when the seller accepted a best offer. soldPrice is the actual accepted amount; the original asking price (higher) was visible as a strikethrough on eBay. Detected from strikethrough + "or Best Offer" signals on the search card.
bidCountnumber | nulloptional
Number of bids received. Present for auction listings, null for fixed-price (Buy It Now) listings.
categoryIdstringoptional
eBay category ID.
endedAtstringoptional
ISO 8601 sold/ended date.
soldPricestring | nulloptional
Sold price as a decimal string.
soldCurrencystring | nulloptional
ISO 4217 currency code (e.g. "USD", "GBP").
shippingPricestring | nulloptional
Shipping cost; "0.00" when free, null when unknown.
shippingType"free" | "paid" | "pickup" | "unknown" | nulloptional
Shipping category.
totalPricestring | nulloptional
soldPrice + shippingPrice when both known.
sellerUsernamestring | nulloptional
eBay seller username.
sellerPositivePercentnumber | nulloptional
Seller positive feedback percentage.
sellerFeedbackScorenumber | nulloptional
Seller total feedback count.
itemLocationstring | nulloptional
Seller's country as shown on the eBay search results page. Localized per site language (e.g., "United States" on ebay.com, "Großbritannien" on ebay.de). null on ebay.co.uk and when eBay omits the location for a listing.
scrapedAtstringoptional
ISO 8601 timestamp of when SoldComps fetched the listing.

Request

curl --request GET \
  --url 'https://sold-comps.p.rapidapi.com/rapidapi/scrape-ebay?keyword=iphone+15+pro&count=240' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: sold-comps.p.rapidapi.com'

Response

{
  "keyword": "iphone 15 pro",
  "page": 1,
  "totalItems": 240,
  "hasNextPage": true,
  "autoSelectedCategory": { "id": "9355", "name": "Cell Phones & Smartphones" },
  "items": [
    {
      "itemId": "256123456789",
      "url": "https://www.ebay.com/itm/256123456789?nordt=true",
      "thumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l500.webp",
      "fullResThumbnailUrl": "https://i.ebayimg.com/images/g/3nkAAeSwCitqGLiR/s-l1600.webp",
      "epid": "20049285656",
      "title": "Apple iPhone 15 Pro 256GB Natural Titanium - Unlocked",
      "condition": "Pre-Owned",
      "conditionId": 3000,
      "sellerType": null,
      "buyingFormat": "buyItNow",
      "bestOfferAccepted": false,
      "bidCount": null,
      "categoryId": "9355",
      "endedAt": "2026-03-10T18:42:00.000Z",
      "soldPrice": "899.99",
      "soldCurrency": "USD",
      "shippingPrice": "0.00",
      "shippingCurrency": "USD",
      "shippingType": "free",
      "totalPrice": "899.99",
      "sellerUsername": "top-deals-store",
      "sellerPositivePercent": 99.8,
      "sellerFeedbackScore": 14200,
      "itemLocation": "United States",
      "scrapedAt": "2026-03-14T21:00:00.000Z"
    }
  ]
}