← compsapi.com

CompsAPI Reference

Real eBay sold prices as JSON. Up to 3 years of history, prices are what buyers actually paid (accepted best offers included), with a trading card layer for graded cards, raw cards and comps. Plus what is listed for sale on eBay right now, from the same key.

https://api.compsapi.com

Quickstart

1. Check your key

Every request sends your key in the X-API-Key header. This call is free and shows your limits.

curl -H "X-API-Key: YOUR_API_KEY" https://api.compsapi.com/v1/usage

2. Get comps for a card

One call returns price stats from every matching sale in the last 90 days, plus the 10 newest sales.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.compsapi.com/v1/comps?q=umbreon+vmax+215/203&grader=PSA&grade=10"

3. Read the answer

{
  "ok": true,
  "query": "umbreon vmax 215/203",
  "page": 1,
  "ms": 2412,
  "count": 84,
  "count_before_filters": 241,
  "no_results": false,
  "next_page": true,
  "days": 90,
  "size": 200,
  "cached": false,
  "cached_age_s": 0,
  "source": "ebay",
  "filters": { "grader": "PSA", "grade": "10", "exclude": "junk" },
  "note": "stats use every matching sale; items shows the 10 newest",
  "stats": {
    "count": 84, "used_for_stats": 84, "median": 3937.0, "mean": 3993.86,
    "p25": 3849.99, "p75": 4058.93, "min": 3375.0, "max": 4650.0,
    "outliers_removed": 0,
    "newest_sale": "2026-10-05T22:46:00Z", "oldest_sale": "2026-09-14T23:45:00Z"
  },
  "items": [
    {
      "item_id": "820200933060",
      "title": "Pokemon TCG Umbreon VMAX 215/203 PSA 10 Evolving Skies",
      "last_sold": "2026-10-05T22:46:00Z",
      "price": 3800.0,
      "format": "FIXED_PRICE",
      "url": "https://www.ebay.com/itm/820200933060",
      "card": { "graded": true, "grader": "PSA", "grade": "10", "grade_label": null,
                "card_number": "215/203", "year": null, "language": null,
                "first_edition": false, "flags": [] }
    }
  ]
}

Same card, ungraded: /v1/comps?q=umbreon+vmax+215/203&graded=false (94 sales, median $1,692.50 at the time of writing).

Authentication

Send your key in the X-API-Key header. Authorization: Bearer YOUR_API_KEY also works. Keep the key on your server; do not ship it in a browser or mobile app.

Get a key, rotate it, and watch your usage in the console. The free plan is 100 requests a month, no card.

Set a User-Agent header on every request (most HTTP libraries do this for you). Requests from Python's built-in urllib without one are blocked by our firewall; requests, httpx, Node fetch, axios, Go and curl all work as is.

Sold listings

GET/v1/sold returns sold listings for a search, newest sale first.

ParameterDefaultDescription
qrequiredSearch terms, max 300 characters. eBay matches every word in the title.
sourceebayWhich marketplace to read. Leave it off for eBay. reverb, stockx, goat, grailed, poshmark, mercari, vinted, goldin, fanatics, myslabs, pristine, tcgplayer or psa reads that source with the same key and quota, and all merges the 12 marketplaces in one call. The eBay options on this page (best_offer, require, print_run, site, category and the card options) do not apply to those sources, and condition takes each marketplace's own labels. See the marketplace reference.
days90How far back to search, 1 to 1095 (3 years).
startoffFirst day of a fixed window, written YYYY-MM-DD. Use start and end to ask for a period that is not a lookback from today, for example start=2024-12-01&end=2025-12-01. Inclusive. On its own it runs to now. A start more than 1095 days ago is refused, and on a plan with less history it is pulled forward to that plan's limit, which plan_limit reports. Several short windows are faster and far more reliable than one deep page walk over the same period.
endoffLast day of a fixed window, written YYYY-MM-DD. Inclusive, so the whole of that day counts, and it never runs past today. On its own the window starts days before it. The answer carries window with the period actually served.
size200Results per page, 10 to 240.
page1Page number, 1 to 200 on Growth and above, 1 to 25 on Starter, 1 to 10 on the free plan. When next_page is true, ask for the next page to get older sales. Walk pages in order: each page is served from where the previous one stopped. A walk stays resumable for 4 hours. A page past 45 asked for on its own, without the pages before it, is refused rather than attempted, because rebuilding the whole walk cannot finish in time. Start from page 1, or narrow the search with start and end instead of paging so deep.
conditionanyOnly sales in that condition: new, open_box, refurbished, used or parts. Comma separate to combine, for example new,open_box. With one value, every item also carries condition. Works on /v1/comps too.
best_offeroff1 adds best_offer to every item: true when the sale is identified as an accepted offer, false when it is not identified as one, which is not the same as a full price sale. only returns accepted best offer sales and nothing else. verify does what 1 does and then cross checks the public sold page, adding best_offer_confidence, asking_price and asking_gap_pct to every row. Use it when it matters whether a sale was negotiated, because eBay's own filter misses some. It costs extra time per call, so it is off by default. Works on /v1/comps too.
requireoffKeep only sales whose title holds every one of these words or phrases, comma separated, for example require=lebron james or require=lebron james,red disco. Matching ignores case and punctuation and lands on whole words, so 2017 matches a 2017-18 title and ron jam matches nothing. Up to 6 terms. This is how you search broadly and then insist on the one thing that identifies your item: eBay widens a long query, so q=lebron james red disco with require=lebron james returns far more of the right sales than spelling the whole card into q. It can only remove rows, never find new ones, so the answer carries title_filter with the count before it ran and how many it removed.
print_runoffThe serial number a card is limited to, read from the title. A number keeps only that print run, for example print_run=125 for a /125 parallel. numbered keeps every serial numbered card. any filters nothing and just labels the rows. All three add print_run to every item. #098/125 reads as 125 and not as 98, a bare /85 reads as 85, and a card number like #100, a 100 card lot and a date are all left alone. A print run is not an identity: a /125 parallel of the same player exists in several seasons at very different prices, so keep the year in q and use this to separate parallels within it, not instead of it. Reported in title_filter the same way.
native_priceoff1 adds native_price and native_currency to every item: the amount in the currency the buyer actually paid, recovered from the listing itself. Sales made on eBay US cost nothing because they are already USD. Each non US sale needs one extra read, so it is capped per request and native_price_info in the response tells you exactly what was covered. Off by default because of that cost. Works on /v1/comps too.
siteoffPin one eBay marketplace, so you get only sales made on that site: US, UK, DE, FR, IT, ES, CA or AU. A pin means that site alone, not listings a buyer there could see. Leave it off for the default, which is eBay US plus international coverage merged. Every price is USD whichever you pick: eBay converts before we receive it, so a pin changes which sales you get, never the currency.
categoryanyeBay category id, comma separate for several, for example 31387 for wristwatches.
min_price / max_priceoffKeep only sales inside the price range. Applied to the page you asked for; price_filter in the response echoes the bounds.
card optionsoffAdd any of the card options to parse, filter and price the results.

Each search covers eBay US plus international eBay sites and a common spelling variant of your terms, merged and de-duplicated, so count can be a little higher than size. Every item carries us_sale so you can separate the US sales from the rest, and site=US returns eBay US alone.

Comps

GET/v1/comps is built for pricing a card. It searches the newest 200 sales over 90 days, removes junk listings (exclude=junk by default), applies your card options and returns stats plus the 10 newest matching sales. Every item carries a card object even with no card options set. One call counts as one request. /v1/comps is not pageable: ignore next_page here and use /v1/sold with page when you need every sale.

ParameterDefaultDescription
qrequiredThe card, as specific as you can (see tips).
sourceebaySame as /v1/sold: a marketplace name or all. See the marketplace reference.
days, size90, 200Same as /v1/sold.
excludejunkPass exclude=none to keep every listing.
card optionsgrader, grade, graded, lang, card_condition, first_edition.

Stats

FieldDescription
countMatching sales with a price.
used_for_statsSales the stats are computed from: count minus outliers_removed.
median, meanMiddle and average sold price (USD) after removing outliers.
p25, p7525th and 75th percentile: the range the middle half of sales fell in.
min, maxLowest and highest price used.
outliers_removedSales more than 3 times the middle range away from it (8+ sales needed), usually mislabeled listings.
newest_sale, oldest_saleThe time span the stats cover (UTC).

Live listings

GET/v1/active returns listings that are for sale on eBay right now, the same listings eBay's own search shows for those words. Same key, same headers, same limits and same errors as /v1/sold, and one call counts as one request. Sold and live are separate searches: to set what is listed against what sold, call both.

ParameterDefaultDescription
qrequiredSearch terms, max 300 characters.
sortbest_matchbest_match (eBay's own order), newly_listed, ending_soonest, price_asc or price_desc.
per_page200Results per page, 10 to 200.
page1Page number. next_page says whether there is another. Your plan's page limit applies, as on /v1/sold.
min_price / max_priceoffPrice range in USD.
conditionanynew, open_box, refurbished, used or parts. Comma separate to combine.
formatbothbin for Buy It Now only, auction for auctions only.
categoryallAn eBay category id, for example 31387 for wristwatches.

Live listings cover eBay US (ebay.com). A site other than US returns 400, and so do since and sorts not listed above.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.compsapi.com/v1/active?q=kitchenaid+mixer&sort=price_asc&condition=used&per_page=50"

Live listing fields

FieldDescription
item_id, title, urleBay item number, listing title and link.
price, currencyThe price now, in USD. On an auction this is the current bid.
shipping, shipping_textCost to a US address as eBay quotes it: 0 when free, null when no price is shown (calculated shipping, freight or collection only). shipping_text is eBay's own wording, for example +$7.50 delivery.
formatBIN (Buy It Now) or AUCTION.
bids, ends_atAuctions only: bids so far and when the auction ends (UTC).
buy_it_now_availableAn auction that also has a Buy It Now price.
best_offer_enabledThe seller accepts offers.
quantity_availableUnits still available on the listing.
conditionThe condition as the listing states it, for example Pre-Owned.
seller, seller_feedback, seller_positive_pctSeller username, feedback score and positive feedback percentage.
location, imageThe country the item is located in, and the main image.
price_maxThe top of the range on a listing that shows a price range, with price as the bottom. null otherwise, which is almost every listing.

Response fields: ok, query, page, ms, sort, count, next_page, source, cached and cached_age_s, plus total_active: how many live listings eBay has for the search. When eBay gives only a rounded figure (for example 12,000+), total_active_is_minimum is true. An identical search within 60 seconds is served from cache (20 seconds with sort=newly_listed).

New listings as they appear

Poll with sort=newly_listed and keep the item_ids you have already seen. Anything new comes back at the top of page 1. Every 30 to 60 seconds per search is plenty, and each poll is one request.

Usage

GET/v1/usage shows searches used today (UTC day), your key's current cap and when it expires. It does not count towards your limit. Monthly plan totals live on your console dashboard. GET /v1/health returns service status and needs no key, for uptime checks.

{"ok": true, "day_utc": "2026-10-09", "used": 1250, "daily_cap": 5000,
 "trial_hours": 72, "trial_started": "2026-10-07T09:12:44Z", "expires": "2026-10-10T09:12:44Z"}

A trial key's clock starts at its first search, so expires is null until then.

Card options

Add these to /v1/sold or /v1/comps. Each item then gets a card object, and the options filter the results. On /v1/sold they filter the page you asked for; count_before_filters shows how many there were before.

OptionExampleKeeps
cards=1Everything, just adds the card object.
graderPSA, BGS,CGCCards graded by these companies. BECKETT counts as BGS. Also SGC, TAG, ACE and others.
grade10, 9.5, 9,10Cards with this grade.
gradedtrue / falseOnly slabs, or only raw cards. "PSA 10 contender" style listings count as raw.
langja, en,jaCards whose title names this language: en ja zh ko de fr it es pt. Titles that name none are left out when you use it.
card_conditionnm, mp,hpRaw card condition claimed in the title: nm near mint, lp lightly played, mp moderately played, hp heavily played, dmg damaged. Graded slabs never match, because a slab's condition is its grade. Short forms are read in context, so "Mew ex", a card's "130 HP", short prints and vinyl LPs are not mistaken for a condition. Every item also carries card.condition.
condition"nm"Raw condition the title claims: nm, lp, mp, hp or dmg. Always null on a graded card, whose condition is its grade.
first_editiontrue1st edition cards only (or false for none).
excludejunk, lot,sealedDrops listings with these flags. junk means lot, mystery, accessory, replica, keyword_stuffing, title_missing and not_graded_claim.
stats=1Adds stats for what is left (on /v1/comps it is always on).
# Which sales were accepted offers
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.compsapi.com/v1/sold?q=omega+speedmaster&days=30&best_offer=1"
# PSA 9 and 10 Japanese Luffy cards, no junk, with stats
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.compsapi.com/v1/sold?q=luffy&grader=PSA&grade=9,10&lang=ja&exclude=junk&stats=1"

Card fields

Read from the listing title. Fields are null when the title does not say.

FieldExampleDescription
gradedtrueThe title names a grading company and a grade.
grader"PSA"PSA, BGS, CGC, SGC, TAG, ACE, AGS, HGA, GMA, MNT or ARS.
grade"9.5"Grade as text, so 9.5 stays exact.
grade_label"pristine"gem mint, pristine, black label, mint or near mint, when stated.
card_number"215/203", "OP05-119"Collector number or set code as written.
year1999Year in the title.
language"ja"Language named in the title.
first_editionfalseTitle says 1st edition.
flags["lot"]Warnings about the listing, see below.

Flags

FlagMeansExample title
lotMore than one card sold together."4 x Ace Grade 10 Charizard Bundle"
mysteryMystery pack, repack or "chance to win" listing."Mystery Graded Slab, chance at PSA 10 Charizard"
sealedSealed product: booster box, pack, ETB, tin."151 Booster Box SV2a Sealed"
accessoryCase, sleeves, binder or display, not a card."Acrylic case for booster box"
replicaCustom, proxy, fan art or fake."Umbreon VMAX Fan Art Holo"
keyword_stuffingSeveral graders named without a grade, usually to show up in searches."Charizard PSA bgs CGC tag"
not_graded_claimRaw card described with a grade ("contender", "potential PSA 10")."Charizard 4/102 PSA 10 Contender"
title_missingThe listing title was not available.

Card fields and flags come from rules that read the title. They catch the common patterns but will miss unusual titles, so treat flags as hints. We report what sold; we do not authenticate cards.

Getting good comps

Item fields

FieldDescription
item_ideBay item number.
titleListing title.
last_soldTime of the most recent sale on this listing (UTC).
priceAverage price actually paid per unit, USD. Accepted best offers show the real offer price, not the asking price.
units_sold, total_salesUnits sold on this listing in the window, and their total value.
formatFIXED_PRICE or AUCTION.
bidsNumber of bids (auctions).
us_saletrue when the sale was made on eBay US, false when it was made on another eBay site. The default search merges eBay US with international coverage, so this is how you tell those rows apart and keep a US only price guide honest without running a search per marketplace. We do not report which other site a false row came from, because eBay does not give us that per item and we would rather give you a field that is always right. With site pinned, every row is true or every row is false by definition.
native_price, native_currencyOnly with native_price=1. The amount in the currency the sale actually happened in, and its ISO 4217 code. A UK sale that we report as 949.58 comes back as GBP 717.94 here. price is always USD; this is the untouched figure. null means we could not confirm it, which happens on a listing that sold several units at different prices, because an average does not correspond to any single displayed amount. native_reason says why a row is null: multi_unit_average (the listing sold several units, so price is an average), listing_active (the listing is still running and its price can change), or price_mismatch (the listing page shows a different amount from the sale, usually an accepted Best Offer, where eBay shows only the asking price). We would rather return null than a number you cannot tell is wrong. Note that converting price back yourself does not reproduce this: eBay converted at the rate on each sale's own day, so a single current rate is off by a few percent and by a different amount on every row.
best_offerOnly with best_offer=1 or only. true: sold as an accepted best offer, and price is the accepted offer. On a listing that sold several units, price is the average actually paid across those sales, so read it with units_sold; pass best_offer=only to average the accepted offers alone. false: not identified as an accepted best offer. Read it as the absence of a positive identification, not as proof the item sold at its displayed price: a fixed price sale can close below the displayed price through a seller markdown, a promotion or a price revision, and none of those is an offer. Only true is a positive assertion. null: outside the window we were able to check (rare, mostly very busy searches).
best_offer_confidenceOnly with best_offer=verify. confirmed: eBay identifies the sale as an accepted offer, either through its offer filter or its own public label. likely: the listing accepted offers and the sale closed materially below the asking price, which is the signature of a negotiated sale that eBay did not label. unlikely: neither holds. unknown: the sale was not on the public pages we read, or you pinned another marketplace, so there was nothing to compare and we do not guess.
asking_price, asking_gap_pctOnly with best_offer=verify. The price eBay's public sold page displays for this listing, and how far above the amount actually paid it sits, as a percentage. This is the evidence behind best_offer_confidence, so you can apply your own threshold instead of ours. asking_gap_pct goes negative on the rare listing where the public page reads low.
print_runOnly with print_run. The run the title says the card is limited to, as a number, or null when the title does not say. Sellers do not always print it, so null means unstated, never unlimited.
shipping_cost, free_shipping_pctAverage shipping charged (null when unknown), and the share of sales with free shipping (0 to 100).
url, imageListing link and main image.
cardWith card options on /v1/sold; always present on /v1/comps. See card fields.

Response fields: ok, query, page, ms (our response time), count, no_results, next_page, days, size, source, cached and cached_age_s (identical searches within 15 minutes come from cache, shared between /v1/sold and /v1/comps), plus site, price_filter, filters, count_before_filters, stats and note when those options apply.

Errors

StatusMeaningWhat to do
400Missing or invalid parameter, or eBay rejected the search as too broad.Fix the request or narrow the terms.
401Missing or invalid API key.Check the X-API-Key header.
403Key expired, or the request was blocked by our firewall (no User-Agent).Set a User-Agent header, or open a ticket.
404Unknown endpoint or path.Check the path against this reference.
429Quota reached, or too many requests at once.Back off a few seconds, or lower your concurrency. See limits.
503Temporary problem on our side.Retry after a second or two.

Failed searches do not count towards your limit. Every error body is JSON with "ok": false and an error message.

Rate limits & quotas

PlanRequests / monthRequests / minHistoryPages per search
Free100103 years10
Starter · $95,0001203 years25
Growth · $2925,0001203 years200
Pro · $79100,0001203 years200
Business · $199300,0001203 years200
Scale · $4991,000,0001203 years200

Once the monthly quota is used a key returns 429 with error: quota_reached and pauses until the UTC month resets. There is no overage charge; upgrade in the console to raise the quota immediately. Bursting past your per minute rate returns 429 with a Retry-After header: back off that many seconds and retry. Console keys also get live X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Monthly and X-Quota-Used headers on every response. Failed searches do not count. Every plan reads the full 1,095 days. A page past your plan's limit returns 400 naming the limit; a start and end window reaches any part of the three years without paging. Upgrade, downgrade or cancel anytime in the console.

Keys issued before the console (and trial keys, which run 72 hours from the first search) carry a daily cap instead; /v1/usage shows whichever cap your key has.

About the data

MCP server

CompsAPI ships a hosted MCP server, so AI agents and assistants (Claude, Cursor and any other MCP client) can pull real sold prices themselves. Add it with your API key:

{
  "mcpServers": {
    "compsapi": {
      "url": "https://api.compsapi.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

It exposes two tools: search_sold_listings (query, days, condition, best_offer, site, category, price range, page), returning price stats plus the newest sales, and search_live_listings (query, sort, condition, format, category, price range, page), returning the asking price spread plus the listings for sale now. Each tool call counts as one request against your quota, same as the REST API.

OpenAPI / Postman

Import https://api.compsapi.com/openapi.json into Postman, Insomnia or any OpenAPI tool to get every endpoint ready to call, or generate a typed client with any OpenAPI code generator. Set your key as the X-API-Key header.

Questions, a missing field, or volume past the pricing page: open a ticket in the console and we reply there, usually within a day.

AI junk filter (optional)

Two optional parameters on /v1/sold and /v1/comps. A call without them answers exactly as before.

ParameterWhat it does
exclude=ai_junkLeaves out the sales our AI model reads as not a single normal item (lots, parts, accessories, empty boxes, mystery listings), from the rows and from the stats.
ai=1Adds an ai object to every returned sale and removes nothing.
"ai": {"kind": "item", "junk": false, "confidence": 0.98, "category": "trading_cards", "model": "2026-11-18"}

kind is what was sold (item, lot, mystery, parts, accessory, box_only, replica, digital or other), junk is what exclude=ai_junk filters on, and model is the release date of the model. meta.ai.status reads ok when the labels were applied. When the filter is busy the call still succeeds: the rows come back unfiltered and meta.ai.status says so.

exclude=junk, the rules filter above, is unchanged, and the two combine as exclude=junk,ai_junk. On /v1/comps, exclude=ai_junk keeps the title rules filter on as well, so it is applied as junk,ai_junk.

On eBay the filter agreed with our labels on about 92% of 690 listings. They came from 20 eBay searches the filter had never seen, and each listing was labelled twice independently and settled by review. It wrongly removed 24 of 413 real items and kept 30 of 277 junk listings, so on eBay the model and the label differ on about 8 listings in 100. In our test searches, about four in ten sold eBay listings were not a single normal item. Those figures measure the filter, not the sold data, which comes back exactly as recorded with or without it. More on the junk filter page.

The same eBay search with and without the filter

Each row is one eBay search three ways: a plain call, with exclude=junk and with exclude=ai_junk. Measured on 18 November 2026. Each eBay figure is the median over the 240 newest sales of the search, not the whole window. Figures are rounded.

eBay searchMedian withoutWith the title rules filterWith the AI filterSales removed by the AI filter
rolex submarinerabout $40about $44about $10,600190 of 239
canon eos r5about $65about $63about $1,810167 of 239
omega seamasterabout $220about $265about $1,900116 of 239
dyson airwrapabout $185about $190about $32095 of 239
pokemon charizard base setabout $46about $115about $250135 of 239
lego millennium falcon 75192about $535about $560about $67578 of 239

What it gets wrong on eBay

Listings that include extra games, controllers or other separate products are left out, so the price reflects the item itself. A normal item sold with its case or charger is kept.