← Marketplace reference

PSA cert lookup, population and card lookup: API reference

Three card endpoints built on PSA's data. /v1/cert takes a PSA cert number and returns the card, its grade, the population at that grade and higher, and the card's recent sales. /v1/lookup resolves a card keyword to its PSA spec id, and /v1/population returns PSA's population report for one card or a whole set: how many copies PSA has graded at each grade. They pair with the sold endpoints: price a card with /v1/sold?source=psa, then read how scarce each grade is. Each call is one request.

https://api.compsapi.com

This page is the technical reference. For coverage, examples and pricing see PSA population on CompsAPI. Parameters, stats, the AI junk filter and errors shared by every source are in the common reference.

/v1/cert: PSA cert number to card, grade and population

Takes the cert number on a PSA slab and returns the card, its grade, how many copies PSA has graded at that grade and how many grade higher, the total graded and gem rate, and the card's most recent sales, in one request.

GET /v1/cert?cert=63700127
GET /v1/cert?cert=63700127&recent=0
{
  "ok": true, "cert": "63700127", "found": true, "source": "psa", "resolved_by": "index",
  "spec_id": 842576, "grade": "10", "grading_company": "PSA",
  "card": { "subject": "Kobe Bryant", "year": "2008", "set": "Topps Chrome", "number": "24",
            "variety": "Refractor", "category": "BASKETBALL CARDS", "spec_id": 842576,
            "url": "https://www.psacard.com/spec/psa/842576" },
  "population": {
    "at_grade": 160, "higher": 0, "total_graded": 339, "gem_rate": 47.2, "has_dual_graded": false,
    "grades": {
      "8": { "graded": 17, "qualifier": 0, "total": 17 },
      "9": { "graded": 149, "qualifier": 0, "total": 149 },
      "10": { "graded": 160, "qualifier": 0, "total": 160 }
    }
  },
  "recent_sales": [
    { "sold_date": "2026-11-16T04:31:00.000Z", "price": 15000, "currency": "USD", "grade": 10,
      "grading_company": "PSA", "cert_number": "63700127", "marketplace": "Fanatics Collect" },
    { "sold_date": "2026-11-12T01:43:06.000Z", "price": 6500, "currency": "USD", "grade": 8,
      "grading_company": "PSA", "cert_number": "93320104", "marketplace": "eBay" }
  ]
}

Trimmed for length: grades lists every grade PSA reports, and recent_sales rows also carry url.

ParameterDefaultMeaning
certrequiredThe PSA cert number, 5 to 12 digits. Anything else returns 400.
recent10How many of the card's most recent sales to include, 0 to 25. 0 leaves them out.
FieldMeaning
foundtrue when the cert resolved to a card. When it is false, reason says why: see when a cert does not resolve.
resolved_byWhere the card came from. index and psa_cert_page are PSA's own record for the cert, with the spec id, population and recent sales. marketplace_listing is a listing of this exact slab on one of the marketplaces we cover: see below.
spec_id, cardPSA's card id and the card it names, the same id /v1/population takes and source=psa rows carry. Answers from PSA's record for the cert can also carry card.description, card.label_type and item_grade (PSA's grade label, such as GEM MT 10).
grade, grading_companyThe grade on this slab.
population.at_gradeCopies PSA has graded at this cert's grade.
population.higherCopies PSA has graded above this cert's grade.
population.total_graded, gem_rate, grades, has_dual_gradedAs on /v1/population.
recent_salesThe card's most recent sales, newest first, across all grades, with price, date, grade, cert number and where it sold.
seen_onOnly when resolved_by is marketplace_listing: the marketplace, date, price, currency, url and image of the listing the slab was seen on.

An answer with resolved_by: "marketplace_listing" has the grade, and the card as the listing titled it (card.title, card.year, card.category), but spec_id, population and the other card fields are null and recent_sales is empty. Ask for the same cert again later to get the full answer once PSA's record for it is read.

When a cert does not resolve

A cert that does not resolve still answers 200 with "ok": true, "found": false, a reason and a plain detail:

reasonMeaningWhat to do
cert_lookup_pendingPSA's record for this cert is being read and took longer than the call allows.Retry the same call after a few seconds (3 to 10 s). It usually resolves on the retry.
cert_not_indexedThe cert could not be resolved to a card at that moment.Retry later. A cert that answers this can resolve on a later call. For the card itself, use /v1/lookup and /v1/population, or /v1/sold?source=psa with the card's keywords.
cert_not_foundPSA has no record of this cert number.Check the number on the slab.

A cert that resolves once is kept, so later calls for it answer at once.

/v1/lookup: keyword to PSA spec id

Resolves a card keyword to PSA spec ids with card details, best match first. The spec id is PSA's id for one card, so you can key your own records to it.

GET /v1/lookup?q=2018+panini+prizm+luka+doncic+280
{
  "ok": true, "query": "2018 panini prizm luka doncic 280", "count": 10, "source": "psa",
  "results": [
    { "spec_id": 2678489, "subject": "Luka Doncic", "year": "2018", "set": "Panini Prizm", "number": "280",
      "variety": null, "category": "Basketball Cards", "description": "2018,Panini Prizm,280,Luka Doncic",
      "url": "https://www.psacard.com/spec/psa/2678489" }
  ]
}
ParameterDefaultMeaning
qrequiredCard keyword: year, set, player, number. Max 300 characters.
limit10How many matches to return, 1 to 25.

/v1/population: PSA grade census for a card

Returns PSA's population report for one spec: the count at each grade, the total graded and the gem rate (the share graded PSA 10). Pass a spec id, or a keyword q to use the top match. For every card in a set at once, pass set (below).

GET /v1/population?spec=2678489
GET /v1/population?q=2018+panini+prizm+luka+doncic+280
{
  "ok": true, "spec_id": "2678489", "source": "psa",
  "gem_rate": 52.16, "total_graded": 40035, "has_dual_graded": true,
  "grades": {
    "authentic": { "graded": 114, "qualifier": 0, "total": 114 },
    "7": { "graded": 248, "qualifier": 0, "total": 248 },
    "8": { "graded": 1408, "qualifier": 2, "total": 1410 },
    "9": { "graded": 16993, "qualifier": 1, "total": 16994 },
    "10": { "graded": 20883, "qualifier": 0, "total": 20883 }
  },
  "psa_spec_url": "https://www.psacard.com/spec/psa/2678489"
}
ParameterMeaning
specA PSA spec id, from /v1/lookup, from card.psa_spec_id on a source=psa row, or from your own records.
qA keyword in place of a spec. It is matched loosely and always resolves to the closest card PSA has, and the response adds resolved_from with the keyword and the matched card. Read resolved_from.card to confirm it is the card you meant, or pass spec.
setA whole set in place of one card: see the next section.
FieldMeaning
gem_rateThe percentage of graded copies at PSA 10. 0.14 means 0.14%.
total_gradedThe full population.
gradesA map from grade label (authentic, 1, 1.5 and so on up to 10) to graded, qualifier and total. qualifier counts copies graded with a qualifier such as OC or MK, and total is the sum.
has_dual_gradedWhether PSA lists dual graded copies for this card.
psa_spec_urlThe card's page on psacard.com.

/v1/population?set=: a whole set's population report

Pass a PSA set id, or the psacard.com pop URL of the set, and get every card in the set with its grade breakdown, 25 cards per page. Each card also carries PSA's sales count, most recent price and average price.

GET /v1/population?set=285178
GET /v1/population?set=https://www.psacard.com/pop/tcg-cards/2024/pokemon-ssp-en-surging-sparks/285178&page=2
{
  "ok": true, "source": "psa", "set_id": 285178,
  "total_items": 414, "page": 1, "page_size": 25, "pages": 17,
  "cards": [
    { "spec_id": 12168502, "number": "001", "subject": "Exeggcute", "variety": null,
      "url": "https://www.psacard.com/spec/psa/12168502",
      "population": { "total_graded": 3, "gem_rate": 33.33, "has_dual_graded": false,
        "grades": { "9": { "graded": 2, "qualifier": 0, "total": 2 }, "10": { "graded": 1, "qualifier": 0, "total": 1 } } } }
  ]
}

Trimmed for length: a page holds 25 cards, and each card and the set also carry the sales figures in the table below.

ParameterDefaultMeaning
setA PSA set id, or the psacard.com pop URL of the set.
page1The page of the set, 25 cards each. pages in the answer says how many there are.
FieldMeaning
set_id, total_items, pagesThe set, how many cards it has and how many pages of 25 that makes.
total_sales, total_valuePSA's sales count and sales value for the whole set.
cards[].spec_id, number, subject, variety, urlThe card and its page on psacard.com. The spec_id works with ?spec= and on source=psa rows.
cards[].number_of_sales, recent_price, avg_pricePSA's sales count, most recent price and average price for the card.
cards[].populationtotal_graded, gem_rate, grades and has_dual_graded, as for one card.

PSA fixes a set page at 25 cards. population is null on a card PSA has no report for. It is also null, with population_error: "psa_unavailable", on a card PSA did not answer for at that moment. Ask for the page again to fill it in. /v1/cert does the same when the population could not be read: the card and grade still come back.

Notes