← 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.

Quickstart

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

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

import requests

r = requests.get(
    "https://api.compsapi.com/v1/comps",
    params={"q": "umbreon vmax 215/203", "grader": "PSA", "grade": "10"},
    headers={"X-API-Key": "YOUR_API_KEY"},
    timeout=30,
)
data = r.json()
print(data["stats"]["median"], "from", data["stats"]["count"], "sales")

const url = new URL("https://api.compsapi.com/v1/comps");
url.search = new URLSearchParams({ q: "umbreon vmax 215/203", grader: "PSA", grade: "10" });

const res = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await res.json();
console.log(data.stats.median, "from", data.stats.count, "sales");

{
  "ok": true,
  "query": "umbreon vmax 215/203",
  "count": 84,
  "count_before_filters": 241,
  "filters": { "grader": "PSA", "grade": "10", "exclude": "junk" },
  "stats": {
    "count": 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", "card_number": "215/203",
                "language": null, "first_edition": false, "flags": [] }
    }
  ]
}

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.

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.

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.

Comps

GET/v1/comps is built for pricing a card. It searches the newest 200 sales over 90 days, removes junk listings, applies your card options and returns stats plus the 10 newest matching sales. One call counts as one request.

Stats

Usage

GET/v1/usage shows searches used today (UTC day), your daily limit and when your key expires. It does not count towards your limit.

{"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.

# 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+psa&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.

Flags

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

• Be specific. Include the card name and number: umbreon vmax 215/203, not umbreon. A broad search returns the newest 200 sales across thousands of cards, which may span only a few hours.
• Let the options do the grading. Search charizard 4/102 base set with grader=PSA&grade=8 rather than putting "psa 8" in q, so titles written "PSA8" or "PSA 8 NM-MT" are still caught.
• Raw vs graded: graded=false gives the raw market for the same card.
• Thin cards: raise days (up to 1095) when a card sells rarely, and check stats.count before trusting a median.

Item fields

Response fields: ok, query, page, ms (our response time), count, no_results, next_page, days, size, cached and cached_age_s (identical searches within 15 minutes come from cache), plus filters, count_before_filters and stats when card options are used.

Errors

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

Limits

Your daily limit, how many requests you can run at the same time, and your expiry are set on your key and listed in the email it came with; /v1/usage always shows them. Trial keys run 72 hours from your first search.

About the data

• Sold listings from eBay US and international eBay sites, up to 3 years back, usually within minutes of the sale.
• Prices are the price actually paid, in USD. Accepted best offers show the real offer price.
• A listing that sold several units appears once, with units_sold and total_sales for the window.
• We return what sold on eBay. We do not verify authenticity or condition beyond what the title says.

OpenAPI / Postman

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

Questions, or something you need added: reply to the email your key came with.