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.
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.
| Parameter | Default | Meaning |
|---|---|---|
cert | required | The PSA cert number, 5 to 12 digits. Anything else returns 400. |
recent | 10 | How many of the card's most recent sales to include, 0 to 25. 0 leaves them out. |
| Field | Meaning |
|---|---|
found | true when the cert resolved to a card. When it is false, reason says why: see when a cert does not resolve. |
resolved_by | Where 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, card | PSA'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_company | The grade on this slab. |
population.at_grade | Copies PSA has graded at this cert's grade. |
population.higher | Copies PSA has graded above this cert's grade. |
population.total_graded, gem_rate, grades, has_dual_graded | As on /v1/population. |
recent_sales | The card's most recent sales, newest first, across all grades, with price, date, grade, cert number and where it sold. |
seen_on | Only 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:
reason | Meaning | What to do |
|---|---|---|
cert_lookup_pending | PSA'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_indexed | The 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_found | PSA 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" }
]
}
| Parameter | Default | Meaning |
|---|---|---|
q | required | Card keyword: year, set, player, number. Max 300 characters. |
limit | 10 | How 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"
}
| Parameter | Meaning |
|---|---|
spec | A PSA spec id, from /v1/lookup, from card.psa_spec_id on a source=psa row, or from your own records. |
q | A 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. |
set | A whole set in place of one card: see the next section. |
| Field | Meaning |
|---|---|
gem_rate | The percentage of graded copies at PSA 10. 0.14 means 0.14%. |
total_graded | The full population. |
grades | A 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_graded | Whether PSA lists dual graded copies for this card. |
psa_spec_url | The 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.
| Parameter | Default | Meaning |
|---|---|---|
set | A PSA set id, or the psacard.com pop URL of the set. | |
page | 1 | The page of the set, 25 cards each. pages in the answer says how many there are. |
| Field | Meaning |
|---|---|
set_id, total_items, pages | The set, how many cards it has and how many pages of 25 that makes. |
total_sales, total_value | PSA's sales count and sales value for the whole set. |
cards[].spec_id, number, subject, variety, url | The 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_price | PSA's sales count, most recent price and average price for the card. |
cards[].population | total_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
- The report is PSA's own.
- Population covers PSA graded cards. A keyword is matched loosely, so check
resolved_from.card. - If PSA's data cannot be read at that moment, the answer is
"ok": falsewitherror: psa_unavailable, and the call is not counted. Retry after a short wait. - The same spec id is on every
source=psasold row ascard.psa_spec_idand on every/v1/certanswer that comes from PSA's record, so certs, sales and population join on one key.