# CompsAPI

Real completed eBay sales as JSON. Up to 1,095 days of history per search, and the
amount a Best Offer sale actually closed at, which eBay's public page never shows.
The same key also returns sold prices from 12 marketplaces beyond eBay (see `source=` below).

Base URL: `https://api.compsapi.com`
Auth: `Authorization: Bearer COMPSAPI_KEY`

## Endpoints

| Endpoint | What it returns |
|---|---|
| `GET /v1/sold` | Individual completed sales matching a query |
| `GET /v1/comps` | A cleaned median, spread and the newest matches |
| `GET /v1/usage` | Quota and limits. Free to call, never counts against quota |

## Parameters for /v1/sold

| Name | Notes |
|---|---|
| `q` | The search. Keep it short. Required |
| `days` | 1 to 1095 on every plan, free included |
| `page` | Older sales when `next_page` is true. Up to page 10 on Free, 25 on Starter, 200 on Growth and above |
| `size` | 10 to 240. Values outside that range are rejected |
| `condition` | new, used, open box, refurbished, parts |
| `best_offer` | `1` adds `best_offer` true or false to every sale. `only` returns accepted offer sales and nothing else. Price is the amount paid either way |
| `cards` | `1` populates the card object. Without it grade and grader are empty |
| `grader` `grade` | PSA, BGS, CGC and the numeric grade. Needs `cards=1` |
| `site` | Pins one marketplace. The default merges several |

## Fields on each sale

`item_id`, `title`, `price`, `last_sold` (UTC), `format` (AUCTION or FIXED_PRICE),
`bids`, `shipping_cost`, `units_sold`, `total_sales`, `best_offer`, `url`, `us_sale`.

## Things that will waste your quota if you do not know them

1. **Long queries return nothing.** Pasting a full listing title is the single most
   common cause of zero results. Search `levis 506 jeans`, not
   `Levi's 00506-0391 jeans mens W34 L32 straight leg dark wash`.
2. **A zero result call still costs a request.** There is no free retry.
3. **Queries under three characters are rejected**, not returned empty.
4. **Card numbers are reused across sets.** `4/102` is Base Set Charizard and a
   modern reprint. Add the set name, or filter with `cards=1 graded=true`.
5. **Scarce items read low.** A retired LEGO set returns instructions and single
   minifigures unless you narrow it. Always quote the median AND the spread.
6. **`best_offer=only` returns offer sales and nothing else.** Use `best_offer=1` to label them and keep every sale.

## Marketplaces beyond eBay (`source=`)

`/v1/sold`, `/v1/comps` and `/v1/active` take `source=` to read one of 12 marketplaces with the same key
and the same fields: `reverb`, `stockx`, `goat`, `grailed`, `poshmark`, `mercari`, `vinted`, `goldin`,
`fanatics`, `myslabs`, `pristine`, `tcgplayer`. `source=all` merges the 12 in one call and every row
says where it sold in `source`. `source=psa` is PSA's auction price record, a separate source that is
not part of `all`. Leave `source` out and you get eBay, as before. `source=all` has no eBay rows.

Every plan includes every source, Free too. One call is one request, `source=all` included.

| Extra field | What it holds |
|---|---|
| `source` | The marketplace the sale happened on |
| `authenticity` | `basis` (`marketplace_verified`, `graded`, `third_party_coa`, `seller_declared`), `verified`, `grader`, `grade`, `cert_number` |
| `flags` | Title rule flags: `lot`, `mystery`, `sealed`, `accessory`, `replica`, `not_graded_claim`, `keyword_stuffing`, `title_missing`, plus `outlier` when stats run |
| `signals` | Days on market, list versus sold discount, listing date, seller rating and sold count, where the marketplace gives them |
| `market` | StockX only: lowest ask, highest bid and sell through as recorded with the sale |
| `ai` | With `ai=1`: `kind` (`item`, `lot`, `mystery`, `parts`, `accessory`, `box_only`, `replica`, `digital`, `other`), `junk`, `confidence`, `category`, `model` (the model's release date) |
| `card.psa_spec_id` | `source=psa` only: PSA's card id, the key for `/v1/population` |
| `raw` | Everything else the marketplace gives, under its own key names |

Parameters that work on marketplace sources: `q`, `days`, `start`, `end`, `page`, `size`, `condition`,
`min_price`, `max_price`, `exclude`, `ai`, `stats`, `native_price`. On these sources `days` runs up to 7000
and the window never starts before 2008-01-01. Sales reach back to: Fanatics Collect 2012, Goldin and Pristine 2013,
Reverb 2014, Grailed 2017, StockX 2019, MySlabs 2020; Poshmark, Mercari and TCGplayer start in November 2025.
`size` is moved to the nearest allowed value when it is out of range, and `/v1/comps` has no `size`.

AI junk filter: `exclude=ai_junk` leaves out what our AI model labels as junk (lots, mystery boxes,
parts, accessories, empty boxes, replicas) from the rows and the stats; `exclude=junk,ai_junk` adds the title rules.
Opt in, on every plan: a plain call returns every sale. `exclude=ai_junk` and `ai=1` also work on eBay calls
(`/v1/sold`, `/v1/comps`), where the model agreed with our labels on about 92% of listings on eBay searches it had never seen.
On eBay `/v1/comps` with `exclude=ai_junk` keeps the title rules filter on as well (applied as `junk,ai_junk`), and
the filtered median covers one page of up to 240 newest sales, so check `stats.count`. The filter does not check
that what is left is the item searched for. If the labelling cannot finish in time the rows come back unfiltered
and `meta.ai.status` says so. On Reverb, `fender stratocaster` reads about $400 without it
and about $900 with it. `meta.ai.dropped` says how many rows it removed. `exclude=parts`, `box_only`, `digital` or
`accessory` removes one kind only. In testing the model agreed with the labels on 97.7% of 600 marketplace listings;
it is weakest on Mercari and Vinted (about 94%) and it is not a counterfeit detector. Those figures measure the
filter, not the sold data, which comes back exactly as recorded with or without it.

Live listings: `GET /v1/active?source=poshmark&q=...` returns what is for sale on that marketplace now.
All 12 marketplaces have live listings, and `source=all` searches them together. `live_status` is an object keyed by
marketplace (`ok`, `ok_cached`, `no_match`, `busy`, `timeout`, `error`, `not_available`) and `sources_failed` lists the ones
that answered `timeout`, `error` or `busy`. A marketplace in `sources_failed` was not reached: retry it, and do not
report "no listings" from a zero `count` while it is listed. `psa` has none (501). StockX and GOAT return one row per product at the
lowest ask; Goldin, Fanatics Collect and Pristine return open auction lots (`price` is the current bid,
with `bids` and `ends_at`). `sort`: `best_match`, `newly_listed`, `price_asc`, `price_desc`, `ending_soonest`; an unknown value is served as
`best_match` and listed in `ignored_params`.
Price, condition and format filters apply to the page of listings read for that call, so narrow `q` first.

Card tools: `GET /v1/lookup?q=2018+panini+prizm+luka+doncic+280` returns PSA spec ids; `GET /v1/population?spec=2678489`
returns the count at every grade and the gem rate.

Things to know:

1. **eBay parameters stay on eBay.** `best_offer`, `cards`, `grader`, `grade`, `graded`, `lang`,
   `first_edition`, `require`, `print_run`, `site` and `category` do nothing on a marketplace source and
   give no error: the answer lists them under `ignored_params`. Put those words in `q` (`q=michael+jordan+psa+10`).
2. **`condition` is an exact match on each marketplace's own label.** Reverb says `Excellent`, Grailed
   says `gently_used`, Poshmark `like_new`, Vinted `very_good`, Fanatics `PSA 10`, GOAT `new`, `used` or `new_with_defects`. The words are the same on sold and live calls. Call once with `stats=1`
   and read `stats.by_condition` for the labels, then filter.
3. **Price filters are `min_price` and `max_price`**, in USD.
4. **On `/v1/comps` the title rules run by default (`exclude=junk`).** They read words, so on gear and
   clothing they miss most parts and accessories: add `exclude=ai_junk`. `exclude=none` keeps every row, in
   the stats too. Compare `count` with `count_before_filters` to see what a filter removed.
5. **Each marketplace names things its own way.** PSA calls Base Set "Pokemon Game"; StockX titles drop
   the brand. If a keyword returns nothing on one source, try the words that marketplace uses.
6. **`psa` is not in `source=all`**, because its sales happened on venues the other sources already
   cover. Ask for it by name.
7. **Read `authenticity.basis` before trusting a grade.** `seller_declared` means the seller said so.
   `verified` is true only for StockX and GOAT checks or a real certificate number.
8. **Mercari is Mercari US and starts in November 2025. Vinted is Vinted US, a sample from 15 November 2026 whose dates are the day a sale was first seen.
   PSA keyword search covers the cards held today, mostly 2025 onward; put the grade in `q` (`q=kobe+bryant+psa+10`). GOAT starts in August 2026. TCGplayer resolves a keyword to one product and returns its sales
   from November 2025, a mix of single sales and weekly rows marked `weekly_bucket` in `raw`, for the most traded products in each game; a card outside that set returns nothing.** Do not chart a trend on Vinted dates.
9. **`market` on StockX is a snapshot recorded with the sale**, not the order book at the sale instant
   and not the book now. For current asks call `/v1/active?source=stockx`.

Reference: https://compsapi.com/docs/marketplaces

## Errors

| Code | Meaning |
|---|---|
| 400 | Bad parameter. The message names it |
| 401 | Key missing, wrong or revoked |
| 429 | Rate limit. Back off, do not hammer |
| 503 | eBay did not answer. Retry once after about a minute |

## Billing

One request is one page of up to 240 sales. Failed requests are not counted.
A call with `source=` set counts the same as an eBay call.
Free is 100 requests a month. Plans and limits: https://compsapi.com/pricing
Marketplaces: https://compsapi.com/marketplaces
