CGC Cards API & Scraper: parameters and responses
This is the reference for the 8 CGC Cards endpoints under /cgc/v1 (cert_lookup, search, card_population, set_population, sets, subcategories, categories and grading_scale) and their 14 parameters. Each endpoint lists its parameters, required or optional, with allowed values and defaults, and comes with a cURL, Python and JavaScript call; every response uses the same { ok, data, meta, error } envelope.
The CGC Cards API returns CGC's own grading data as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
cert_lookup takes the certification number printed on a CGC slab and returns what CGC has on file for it: the card or player, game or sport, set, card number, year, language, variants, rarity, the grade as printed (PRISTINE 10, GEM MINT 10, 9, AUTHENTIC) with CGC's grade name, the autograph grade when there is one, the grade date, front and back photos of the slab, and how many copies of that card CGC has graded at that grade and above. card_population and set_population return CGC's population table: for each card the count at Perfect 10, Pristine 10, Gem Mint 10, Mint+ 9.5 and every grade down to 1, plus Authentic and Authentic Altered, with the total, the number of 10s, the share of 10s and the highest grade reached. search finds a card by name, player, set or number across trading card games, sports and non-sports; categories, subcategories and sets walk CGC's own report from game to series to set. grading_scale returns CGC's published definition of every grade. No account, no browser - one ReefAPI key and the standard { ok, data, meta, error } envelope.
CGC has three different 10s - and a 1999 Base Set Charizard has 298 of them out of 15,118
CGC's population report splits the top grade three ways. Measured on 2026-11-08 for Pokémon Base Set Unlimited Charizard 4/102: 15,118 graded, 1 Perfect 10, 11 Pristine 10, 286 Gem Mint 10 - a 2% share of 10s. For a 2025 Japanese Haunter from the Mega Gengar ex starter set the same share is 82%, with 4,796 Pristine 10s. The API returns each column separately, never one merged '10'.
| CGC grade | key in by_grade | what it means |
|---|---|---|
| Perfect 10 | perfect_10 | Retired top grade: Pristine with all four sub-grades at 10; old slabs keep it |
| Pristine 10 | pristine_10 | Virtually flawless, 50/50 centering; gets CGC's Pristine label |
| Gem Mint 10 | gem_mint_10 | A 10 that misses one Pristine criterion (centering up to 55/45) |
| Mint+ 9.5 … Poor 1 | 9.5 … 1 | Numeric grades, half points included |
| Authentic / Authentic Altered | authentic / authentic_altered | Genuine but not numerically graded / altered (e.g. trimmed) |
total counts Authentic and Authentic Altered too, exactly as CGC prints it; numeric_graded and gem_rate_percent leave them out, so the share of 10s is over cards that received a number. In a cert lookup, 'higher grades' is CGC's own figure: the sum of every column above the slab's grade, Perfect 10 first.
Real request and response JSON
Captured from the indexed primary action, cert_lookup, on .
{
"method": "POST",
"url": "https://api.reefapi.com/cgc/v1/cert_lookup",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"cert_number": "6090960083"
}
}{
"ok": true,
"meta": {
"api": "cgc",
"endpoint": "cert_lookup",
"mode": "live",
"latency_ms": 1351.2,
"record_count": 1,
"bytes": 109699,
"cache_hit": false,
"source": "www.cgccards.uk",
"charged_credits": 2,
"version": "0.1.0",
"request_id": "f50b06abc7d04dcb",
"queue_ms": 1.2,
"fetched_at": "2026-11-08T13:04:20.743Z"
},
"data": {
"cert": {
"cert_number": "6090960083",
"grading_company": "CGC",
"collectible": "tcg",
"subject": "Haunter",
"card_name": "Haunter",
"player_name": null,
"game": "Pokémon",
"category": "Pokémon",
"year": "2025",
"manufacturer": null,
"set": "ex Starter Set",
"subset": null,
"card_number": "022/021",
"language": "Japanese",
"rarity": null,
"variants": [
"Mega Gengar ex Set",
"Holo"
],
"attributes": null,
"grade": "PRISTINE 10",
"grade_name": "Pristine 10",
"grade_number": 10,
"designation": null,
"subgrades": null,
"autograph_grade": null,
"grade_date": "2025-10-18",
"images": [
{
"side": "front",
"url": "https://ccg-imaging-cgc-tradingcards-production.s3.amazonaws.com/17607321-05e4-4830-89a4-4d06684e7cf7/CAR6090960-083_OBV.jpg",
"thumbnail_url": "https://ccg-imaging-cgc-tradingcards-production.s3.amazonaws.com/17607321-05e4-4830-89a4-4d06684e7cf7/TN_CAR6090960-083_OBV.jpg"
},
{
"side": "back",
"url": "https://ccg-imaging-cgc-tradingcards-production.s3.amazonaws.com/17607321-05e4-4830-89a4-4d06684e7cf7/CAR6090960-083_REV.jpg",
"thumbnail_url": "https://ccg-imaging-cgc-tradingcards-production.s3.amazonaws.com/17607321-05e4-4830-89a4-4d06684e7cf7/TN_CAR6090960-083_REV.jpg"
}
],
"population_id": "2325252",
"other_fields": null,
"cert_url": "https://www.cgccards.com/certlookup/6090960083/"
},
"population": {
"population_at_grade": 4796,
"population_higher": 0,
"top_pop": true,
"card": {
"population_id": "2325252",
"name": "Haunter",
"card_number": "022/021",
"year": "2025",
"variant": "Mega Gengar ex Set Holo",
"description": null,
"language": "Japanese",
"language_id": 311,
"set_id": "34488",
"collectible": "tcg",
"population": {
"total": 10912,
"numeric_graded": 10906,
"by_grade": {
"1": "[trimmed-depth]",
"2": "[trimmed-depth]",
"3": "[trimmed-depth]",
"4": "[trimmed-depth]",
"5": "[trimmed-depth]",
"6": "[trimmed-depth]",
"7": "[trimmed-depth]",
"8": "[trimmed-depth]",
"9": "[trimmed-depth]",
"perfect_10": "[trimmed-depth]",
"pristine_10": "[trimmed-depth]",
"gem_mint_10": "[trimmed-depth]",
"9.5": "[trimmed-depth]",
"8.5": "[trimmed-depth]",
"7.5": "[trimmed-depth]",
"6.5": "[trimmed-depth]",
"5.5": "[trimmed-depth]",
"4.5": "[trimmed-depth]",
"3.5": "[trimmed-depth]",
"2.5": "[trimmed-depth]",
"1.5": "[trimmed-depth]",
"authentic": "[trimmed-depth]",
"authentic_altered": "[trimmed-depth]"
},
"grades": [
"[trimmed-depth]",
"[trimmed-depth]",
"[trimmed-depth]"
],
"perfect_10": 0,
"pristine_10": 4796,
"gem_mint_10": 4191,
"ten_total": 8987,
"gem_rate_percent": 82.4,
"authentic": 6,
"authentic_altered": 0,
"highest_grade": {
"grade": "[trimmed-depth]",
"grade_number": "[trimmed-depth]",
"count": "[trimmed-depth]"
}
},
"updated_at": "2026-11-07T09:15:48.967",
"url": "https://www.cgccards.com/population-report/redirect/G/2325252/"
},
"category": {
"category_id": "2",
"name": "Pokémon"
},
"subcategory": {
"subcategory_id": "934",
"name": "Starter Decks"
},
"set": {
"set_id": "34488",
"name": "Mega Gengar ex Starter Set - mBG",
"set_name": "Mega Gengar ex Starter Set - mBG",
"subcategory_id": "934",
"population_count": 33448,
"language": null,
"language_id": 311,
"updated_at": "2026-11-08T04:01:52.167",
"url": "https://www.cgccards.com/population-report/tcg/pok%C3%A9mon/2/starter-decks/934/mega-gengar-ex-starter-set-mbg/34488/"
}
}
}
}What the CGC Cards API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| cert_lookup | Verify a CGC-graded card by its certification number (the number on the slab label): card name or player, game, set, card number, year, language, variants, rarity, attributes, grade as printed (e.g. PRISTINE 10, GEM MINT 10, 9, AUTHENTIC) with CGC's grade name and number, autograph grade, sub-grades when the label carries them, grade date, front/back slab images, and that card's population (how many CGC graded at this grade and above, full grade breakdown). An unknown cert returns NOT_FOUND (not charged). | Pricing teams call cert_lookup to verify a CGC-graded card by its certification number (the number on the slab label). | cert_number, include_population, max_rotations |
| search | Find cards in CGC's population report by name, player, set or number ("charizard base set", "tom brady 2000", "luffy op01") across trading card games, sports and non-sports. Returns the population_id that card_population takes, plus set, year, number, variant, language. CGC answers at most 50 matches per collectible type. | Marketplace operators call search to find cards in CGC's population report by name, player, set or number ("charizard base set", "…. | query, collectible, category, year, language, ... |
| card_population | One card's CGC population: how many copies CGC graded at every grade - Perfect 10, Pristine 10, Gem Mint 10, Mint+ 9.5, 9 down to 1, Authentic, Authentic Altered - with total, number of 10s, gem rate and highest grade reached, plus the card's game/sport, series and set. | Catalog enrichment teams call card_population to get one card's CGC population. | population_id, collectible, max_rotations |
| set_population | Every card CGC has graded from one set, 50 a page, each with its count at every grade (Perfect 10 … 1, Authentic), total, 10s and gem rate - CGC's set population table. Filter by card name or number inside the set. | Retail analysts call set_population to get every card CGC has graded from one set, 50 a page, each with its count at every grade (Perfec…. | set_id, collectible, query, page, max_rotations |
| sets | The sets CGC files under one series (e.g. Pokémon › Scarlet & Violet, Baseball › 1980s), 50 a page, with how many cards CGC graded from each; TCG sets come per language. Sort by most graded or name, filter by name or language. | Pricing teams call sets to get the sets CGC files under one series (e.g. | subcategory_id, collectible, query, language, sort, ... |
| subcategories | The series / eras CGC files under one game or sport (Pokémon: Original Series, Neo, … Scarlet & Violet, Mega Evolution, Promotional; Baseball: 2020-Present, 2010s … Pre-1900), with how many cards CGC graded in each. | Marketplace operators call subcategories to get the series / eras CGC files under one game or sport (Pokémon. | category, collectible, max_rotations |
| categories | Every game, sport and non-sports line in CGC's population report with how many cards CGC graded in each (Pokémon ~13 million, One Piece, Magic, Yu-Gi-Oh!, Lorcana and 450+ more TCGs; baseball, basketball, football …; Pokémon Topps, Marvel, Star Wars, phone cards …), most graded first, plus when CGC last refreshed the report. | Catalog enrichment teams call categories to get every game, sport and non-sports line in CGC's population report with how many cards CGC grad…. | collectible, query, sort, max_rotations |
| grading_scale | CGC Cards' published grading scale: every grade from Pristine 10 to Poor 1 with CGC's definition, the Authentic / Authentic Altered / Authentic ART designations, the autograph grade scale (10 to 5, AU), the legacy-grade key (old Gem Mint 9.5 and Perfect 10 labels) and the telephone-card scale. | Retail analysts call grading_scale to get cGC Cards' published grading scale. | max_rotations |
Call cert_lookup from your stack
curl -X POST https://api.reefapi.com/cgc/v1/cert_lookup \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"cert_number":"6090960083"}'import os
import requests
REEF_KEY = os.environ["REEF_KEY"]
r = requests.post(
"https://api.reefapi.com/cgc/v1/cert_lookup",
headers={"x-api-key": REEF_KEY},
json={
"cert_number": "6090960083"
},
timeout=90,
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/cgc/v1/cert_lookup", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"cert_number": "6090960083"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.cgc.cert_lookup with {"cert_number":"6090960083"}.Who uses this API and why
- Slab verification at checkout or in a marketplace listing: cert number in, card, grade and CGC's photos out
- Population-aware pricing: how many copies exist above the grade being sold
- Grading ROI: the share of 10s CGC gave a card before you submit yours
- Set trackers and registries: every card of a set with its graded counts
- Cross-grader research next to PSA and BGS data from other engines
Questions developers ask before integrating
Can I verify a CGC slab by its certification number?
Yes. cert_lookup takes the 10-digit number on the label (or a CGC cert URL) and returns the card, set, number, year, language, variants, the grade as printed with CGC's grade name, autograph grade, grade date and the front and back photos CGC took of the slab. An unknown number returns NOT_FOUND and costs nothing; CGC notes that a cert only appears once the order has shipped.
How many copies of a card has CGC graded at each grade?
card_population returns all 23 columns of CGC's report for one card - Perfect 10, Pristine 10, Gem Mint 10, Mint+ 9.5, 9 down to 1, Authentic and Authentic Altered - plus the total, the number of 10s, the share of 10s and the highest grade reached. set_population returns the same for every card in a set, 50 cards a page. Every value matched CGC's own population page in our 2026-11-08 check (7 cards, 24 cells each).
Does it cover sports cards and non-Pokémon games?
Yes. CGC's report has 461 trading card game categories (Pokémon, One Piece, Magic, Yu-Gi-Oh!, Lorcana, Weiss Schwarz, Dragon Ball and hundreds more), 14 sports (baseball, basketball, football, soccer, hockey …, filed by decade) and 111 non-sports lines (Pokémon Topps and Carddass, Marvel, Star Wars, phone cards …). On 2026-11-08 that was about 14.4 million TCG cards, 4.0 million sports cards and 1.8 million non-sports cards.
What is the difference between Pristine 10 and Gem Mint 10?
Both are 10s on CGC's scale. Pristine 10 is virtually flawless with 50/50 centering and gets CGC's Pristine label; Gem Mint 10 is a 10 that misses one Pristine criterion (centering up to 55/45 front, 75/25 back). The API keeps them apart in every population and names the grade the way CGC prints it. grading_scale returns CGC's full published definitions.
Does it return sub-grades?
When the cert page prints them, cert_lookup returns centering, corners, edges and surface. CGC stopped offering sub-grades in 2023, and none of the 70 recent certs we sampled carried them, so for most slabs subgrades is null.
How do I find a card if I do not know its CGC id?
search with the card name, player, set or number ("charizard base set", "tom brady 2000"), optionally narrowed by game or sport, year and language. CGC answers with its top 50 matches per card type; every row carries the population_id that card_population takes, and include_population attaches the counts to the first 10 rows.
What is the CGC Cards API?
CGC Cards API is a ReefAPI endpoint group for cgc's own graded-card population report and cert verification as json: how many copies cgc graded at every grade, for pokémon, magic, one piece, sports and 580+ categories. It returns live JSON through POST requests under /cgc/v1.
Is the CGC Cards API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. CGC Cards calls use the same shared credit balance as every other ReefAPI engine.
Do I need a CGC Cards login or account?
No login to CGC Cards is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the CGC Cards data?
The page example is captured from a live cert_lookup call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the CGC Cards API use?
CGC Cards actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call CGC Cards from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call cgc actions with the same key, credit pool and JSON envelope used by normal REST requests.
Is the CGC Cards API a CGC Cards scraper?
It is the managed alternative to a DIY CGC Cards scraper. Instead of building and maintaining your own scraper — proxies, headless browsers, captcha and constant breakage — you call one ReefAPI endpoint and get the same cgc's own graded-card population report and cert verification as json: how many copies cgc graded at every grade, for pokémon, magic, one piece, sports and 580+ categories back as clean JSON.
Why does my CGC Cards scraper keep getting blocked?
Most CGC Cards scrapers break on anti-bot defenses, rate limits and IP bans that need rotating residential proxies and browser fingerprinting to clear. ReefAPI handles all of that for you — no proxies, no captchas, no maintenance — and returns live JSON. Blocked calls are free.