# GemRate API scraper - universal graded card population report across PSA, Beckett (BGS), SGC and CGC: population by grade, gem rates, card and set pop reports, population history, most-graded cards, athlete checklists and daily grading volume. Sports cards and TCG (Pokemon, Magic, One Piece). No account.

> Find graded cards across PSA, BGS, SGC and CGC by free text (year, set, player or character, card number, parallel): each match with its GemRate id, total graded population, gem count, gem rate, which graders are included and the card image. 10 matches per page, up to 5 pages.
> ReefAPI engine `gemrate` · 13 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/gemrate/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/gemrate/v1/search — 2 credits
Find graded cards across PSA, BGS, SGC and CGC by free text (year, set, player or character, card number, parallel): each match with its GemRate id, total graded population, gem count, gem rate, which graders are included and the card image. 10 matches per page, up to 5 pages.

**Parameters:**
- `query` (string, required) — Free text: player or character, year, set, card number, parallel.
- `page` (integer, optional, default 1) — Results page (1-5; the site serves at most 50 matches).

**Returns:** query, results[]{gemrate_id, description, year, set_name, name, card_number, parallel, category, total_population, gems, gem_rate, gem_rate_percent, graders_included[], is_universal_match, image_front, url}, count, page, has_more

**Example request body:**
```json
{
  "query": "charizard base set"
}
```

### POST https://api.reefapi.com/gemrate/v1/card — 3 credits
One card's full population report across PSA, Beckett, SGC and CGC: combined population and gem rate, the count at every grade on GemRate's universal scale with percent of total and percent graded higher, and per grader the total graded, gem count, gem rate, every grade count including half grades, PSA qualified grades, the grader's own card name and set, the last population change and front/back images.

**Parameters:**
- `gemrate_id` (string, optional) — The card's GemRate id from `search` (40 characters) or its gemrate.com/card/… URL.
- `query` (string, optional) — Instead of gemrate_id: free text; the best match is used and reported in `match`.

**Returns:** card{gemrate_id, universal_gemrate_id, description, year, set_name, name, card_number, parallel, category, population_type, graders_included[], total_population, gems, gem_rate, gem_rate_percent, universal_grades[]{grade, label, count, percent_of_total, percent_graded_higher}, qualified_grades[]{grade, count}, by_grader[]{grader, grader_name, total_graded, gems, gem_rate, gem_rate_percent, grades[]{grade (e.g. 10, 9.5, 10 Pristine, 10 Black Label, Auth), count, universal_grade, is_gem}, qualified_grades[], qualified_total, last_population_change, grader_card{gemrate_id, description, year, set_name, name, card_number, parallel, category, spec_id}, grader_pop_report_url, set_pop_url}, last_population_change, data_last_updated, image_front, image_back, url}, match{query, matched, other_matches[]} (query input only)

**Example request body:**
```json
{
  "gemrate_id": "ffb8699bb7f435eff4e9761f8e29358e351d777e"
}
```

### POST https://api.reefapi.com/gemrate/v1/card_history — 4 credits
How a card's graded population has grown: BGS and SGC weekly history for the last year with every grade count, gems and gem rate each week; PSA weekly total graded for the last year plus graded past month, prior month, past-month gem rate, 30-day momentum, last gem date and the most recent cert.

**Parameters:**
- `gemrate_id` (string, optional) — The card's GemRate id from `search` (40 characters) or its gemrate.com/card/… URL.
- `query` (string, optional) — Instead of gemrate_id: free text; the best match is used and reported in `match`.
- `grader` (enum, optional, default "all") — Which grader's history. CGC history is not published by the site. [one of: all, psa, bgs, sgc]
- `year` (string, optional) — With grader bgs/sgc and no gemrate_id: the grader's own card fields (set_pop rows carry them as trend_params).
- `category` (string, optional) — With the fields form: the grader's category slug (e.g. tcg-cards, basketball-cards).
- `set_name` (string, optional) — With the fields form: the grader's own set name.
- `name` (string, optional) — With the fields form: the grader's own card name.
- `card_number` (string, optional) — With the fields form: card number as the grader lists it.
- `parallel` (string, optional) — With the fields form: parallel / variety, if any.

**Returns:** gemrate_id, description, histories[]{grader, total_graded, gems, gem_rate, last_population_change, history[]{date, total_graded, gems, gem_rate, grades[]{grade (e.g. 10, 9.5, 10 Pristine, 10 Black Label, Auth), count, universal_grade, is_gem}} (bgs/sgc), weekly_total_graded_1y[] (psa, oldest first, 52 weekly points, dates not published), graded_past_month, graded_prior_month, gem_rate_past_month, momentum_30d_percent, last_gem_date, recent_cert{cert_number, grade, url} (psa), available, note}

**Example request body:**
```json
{
  "gemrate_id": "ffb8699bb7f435eff4e9761f8e29358e351d777e"
}
```

### POST https://api.reefapi.com/gemrate/v1/set_pop — 4 credits
A set's population report from one grader (PSA, BGS, SGC or CGC): every card and parallel with total graded, gems, gem rate and the count at each grade. PSA rows add graded past month and prior month, 30-day gem rate and momentum, the last-year weekly trend, last gem date and a recent cert number. Filter by player/character name, sort, paginate.

**Parameters:**
- `grader` (enum, optional, default "psa") — Grading company. 'beckett' is accepted for bgs. [one of: psa, bgs, sgc, cgc]
- `year` (string, required) — Set year (4 digits).
- `category` (enum, required) — Card category (aliases accepted: pokemon/tcg/magic → tcg-cards, baseball, basketball, football, hockey, soccer, golf, boxing, non-sport, multi-sport…). [one of: baseball-cards, basketball-cards, football-cards, hockey-cards, soccer-cards, tcg-cards, non-sport-cards, multi-sport-cards, boxing-wrestling-cards-mma, golf-cards, minor-league-cards, misc-cards, baseball-coins, basketball-coins, football-coins, hockey-coins, multi-sport-coins, non-sports-coins, packs, pins, tickets]
- `set_name` (string, required) — The set name exactly as the grader spells it (from `sets`, a card's by_grader rows, or `top_cards`).
- `name` (string, optional) — Only cards whose name contains this text.
- `sort` (enum, optional, default "total_desc") — Row order. [one of: total_desc, gems_desc, gem_rate_desc, gem_rate_asc, total_asc]
- `limit` (integer, optional, default 100) — Rows per page (1-1000).
- `page` (integer, optional, default 1) — Page of rows.
- `min_total` (integer, optional, default 0) — Only rows with at least this many graded.

**Returns:** grader, year, category, set_name, set_totals{cards, total_graded, gems, gem_rate}, results[]{gemrate_id (psa), card_number, name, parallel, subset (cgc), description (psa), total_graded, gems, gem_rate, gem_rate_percent, grades[]{grade (e.g. 10, 9.5, 10 Pristine, 10 Black Label, Auth), count, universal_grade, is_gem}, half_and_qualified_total, graded_past_month, graded_prior_month, gem_rate_past_month, momentum_30d_percent, weekly_total_graded_1y[], last_gem_date, recent_cert{} (psa), trend_params{} (bgs/sgc), url}, count, page, limit, total_rows, has_more, sort, source_url

**Example request body:**
```json
{
  "year": "1999",
  "category": "tcg-cards",
  "set_name": "Pokemon Game"
}
```

### POST https://api.reefapi.com/gemrate/v1/sets — 2 credits
Every set a grader has graded for one year and category, with total graded, gems and gem rate per set (the set names to use in set_pop and set_history).

**Parameters:**
- `grader` (enum, optional, default "psa") — Grading company. 'beckett' is accepted for bgs. [one of: psa, bgs, sgc, cgc]
- `year` (string, required) — Set year (4 digits).
- `category` (enum, required) — Card category (aliases accepted: pokemon/tcg/magic → tcg-cards, baseball, basketball, football, hockey, soccer, golf, boxing, non-sport, multi-sport…). [one of: baseball-cards, basketball-cards, football-cards, hockey-cards, soccer-cards, tcg-cards, non-sport-cards, multi-sport-cards, boxing-wrestling-cards-mma, golf-cards, minor-league-cards, misc-cards, baseball-coins, basketball-coins, football-coins, hockey-coins, multi-sport-coins, non-sports-coins, packs, pins, tickets]
- `query` (string, optional) — Only sets whose name contains this text.
- `sort` (enum, optional, default "total_desc") — Row order. [one of: total_desc, gems_desc, gem_rate_desc, gem_rate_asc, total_asc]
- `limit` (integer, optional, default 100) — Rows per page (1-1000).
- `page` (integer, optional, default 1) — Page of rows.
- `min_total` (integer, optional, default 0) — Only rows with at least this many graded.

**Returns:** grader, year, category, results[]{set_name, total_graded, gems, gem_rate, gem_rate_percent}, count, total_rows, has_more, totals{sets, total_graded, gems}

**Example request body:**
```json
{
  "year": "1999",
  "category": "tcg-cards"
}
```

### POST https://api.reefapi.com/gemrate/v1/set_history — 2 credits
A set's grading history: total graded and gems every day the population changed, with graded in the last 7, 30 and 365 days. PSA back to 2021 for sports and TCG; BGS (from late 2021) and SGC (from 2022) for sports sets.

**Parameters:**
- `grader` (enum, optional, default "psa") — PSA, BGS or SGC (no CGC set history; BGS and SGC history covers sports sets, not TCG). [one of: psa, bgs, sgc]
- `year` (string, required) — Set year (4 digits).
- `category` (enum, required) — Card category (aliases accepted: pokemon/tcg/magic → tcg-cards, baseball, basketball, football, hockey, soccer, golf, boxing, non-sport, multi-sport…). [one of: baseball-cards, basketball-cards, football-cards, hockey-cards, soccer-cards, tcg-cards, non-sport-cards, multi-sport-cards, boxing-wrestling-cards-mma, golf-cards, minor-league-cards, misc-cards, baseball-coins, basketball-coins, football-coins, hockey-coins, multi-sport-coins, non-sports-coins, packs, pins, tickets]
- `set_name` (string, required) — The set name exactly as the grader spells it (from `sets`, a card's by_grader rows, or `top_cards`).
- `days` (integer, optional) — Only the last N days of history (default: everything).

**Returns:** grader, year, category, set_name, latest{date, total_graded, gems, gem_rate}, graded_last_7_days, graded_last_30_days, graded_last_365_days, history[]{date, total_graded, gems, gem_rate}, count

**Example request body:**
```json
{
  "year": "1999",
  "category": "tcg-cards",
  "set_name": "Pokemon Game"
}
```

### POST https://api.reefapi.com/gemrate/v1/top_cards — 2 credits
The most graded cards of all time at PSA, BGS, SGC or CGC, overall or in one category: rank, year, set, player or character, card number, parallel, total graded, gems and gem rate.

**Parameters:**
- `grader` (enum, optional, default "psa") — Grading company. 'beckett' is accepted for bgs. [one of: psa, bgs, sgc, cgc]
- `category` (enum, optional) — Optional category (default: all categories). [one of: baseball-cards, basketball-cards, football-cards, hockey-cards, soccer-cards, tcg-cards, non-sport-cards, multi-sport-cards, boxing-wrestling-cards-mma, golf-cards, minor-league-cards, misc-cards, baseball-coins, basketball-coins, football-coins, hockey-coins, multi-sport-coins, non-sports-coins, packs, pins, tickets]
- `limit` (integer, optional, default 100) — How many cards (the site publishes the top 100, 500 or 1000).

**Returns:** grader, category, results[]{rank, year, set_name, name, card_number, parallel, category, total_graded, gems, gem_rate, gem_rate_percent}, count

**Example request body:**
```json
{
  "grader": "psa",
  "limit": 20
}
```

### POST https://api.reefapi.com/gemrate/v1/player — 5 credits
Every graded card of one athlete or character at one grader (a full checklist with population): year, set, card number, parallel, total graded, gems, gem rate and, at PSA, the card id and a recent cert. Filter by year or set, sort, paginate.

**Parameters:**
- `player` (string, required) — Athlete or character name as graders spell it (Michael Jordan, Pikachu).
- `grader` (enum, optional, default "psa") — Grading company. 'beckett' is accepted for bgs. [one of: psa, bgs, sgc, cgc]
- `category` (enum, optional) — Optional category (default: all). [one of: baseball-cards, basketball-cards, football-cards, hockey-cards, soccer-cards, tcg-cards, non-sport-cards, multi-sport-cards, boxing-wrestling-cards-mma, golf-cards, minor-league-cards, misc-cards, baseball-coins, basketball-coins, football-coins, hockey-coins, multi-sport-coins, non-sports-coins, packs, pins, tickets]
- `year` (string, optional) — Only cards from this year.
- `set_name` (string, optional) — Only cards whose set name contains this text.
- `sort` (enum, optional, default "total_desc") — Row order. [one of: total_desc, gems_desc, gem_rate_desc, gem_rate_asc, total_asc, year_desc, year_asc]
- `limit` (integer, optional, default 100) — Rows per page (1-1000).
- `page` (integer, optional, default 1) — Page of rows.
- `min_total` (integer, optional, default 0) — Only rows with at least this many graded.

**Returns:** player, grader, category, totals{cards, total_graded, gems}, results[]{year, set_name, name, card_number, parallel, category, total_graded, gems, gem_rate, gem_rate_percent, half_and_qualified_total, gemrate_id, universal_gemrate_id, recent_cert{cert_number, grade, url}, url}, count, page, limit, total_rows, has_more

**Example request body:**
```json
{
  "player": "Shohei Ohtani"
}
```

### POST https://api.reefapi.com/gemrate/v1/universal_sets — 3 credits
GemRate's Universal Pop Report sets (cards matched across PSA, BGS, SGC and CGC): each set with total graded, each grader's count and market share, checklist size and how many cards have grades.

**Parameters:**
- `category` (string, optional) — Baseball, Basketball, Football, Hockey, Soccer, TCG…
- `year` (string, optional) — Only sets from this year.
- `query` (string, optional) — Only sets whose name contains this text.
- `limit` (integer, optional, default 500) — Sets per page (1-1000; the report has ~400).
- `page` (integer, optional, default 1) — Page of rows.

**Returns:** results[]{set_id, year, set_name, category, total_graded, checklist_size, cards_with_grades, percent_with_grades, by_grader[]{grader, total_graded, share_percent}, recently_added, url}, count, total_rows, has_more

**Example request body:**
```json
{
  "category": "TCG"
}
```

### POST https://api.reefapi.com/gemrate/v1/universal_set — 3 credits
One Universal Pop Report set: every card with its combined population and gem rate, the universal grade breakdown and each grader's total, gems, gem rate, grade counts, last graded and last gem date.

**Parameters:**
- `set_id` (string, optional) — Set id from universal_sets (or the set's gemrate.com URL).
- `year` (string, optional) — With set_name instead of set_id.
- `set_name` (string, optional) — Instead of set_id: the set name from universal_sets.
- `name` (string, optional) — Only cards whose name contains this text.
- `sort` (enum, optional, default "total_desc") — Row order. [one of: total_desc, gems_desc, gem_rate_desc, gem_rate_asc, total_asc]
- `limit` (integer, optional, default 100) — Rows per page (1-1000).
- `page` (integer, optional, default 1) — Page of rows.
- `min_total` (integer, optional, default 0) — Only rows with at least this many graded.

**Returns:** set{set_id, year, set_name, category, url}, totals{cards, total_graded, gems}, results[]{checklist_id, year, set_name, name, card_number, parallel, category, description, total_graded, gems, gem_rate, gem_rate_percent, universal_grades[]{grade, label, count}, by_grader[]{grader, total_graded, gems, gem_rate, grades[]{grade (e.g. 10, 9.5, 10 Pristine, 10 Black Label, Auth), count, universal_grade, is_gem}, description, last_graded, last_gem_date, data_date, gemrate_id, grader_pop_report_url}}, count, total_rows, has_more

**Example request body:**
```json
{
  "set_id": "535f4f725225a27e2c76df910cccab6c4659803d"
}
```

### POST https://api.reefapi.com/gemrate/v1/set_search — 2 credits
Find PSA sets by name across every year and category (e.g. '2023 prizm basketball'): year, category, the set name to use in set_pop / set_history and the set's total PSA graded.

**Parameters:**
- `query` (string, required) — Year, brand, product and sport words (at least 3 characters). PSA sets only - the site offers this search for PSA.

**Returns:** query, results[]{year, category, set_name, description, psa_total_graded}, count

**Example request body:**
```json
{
  "query": "charizard base set"
}
```

### POST https://api.reefapi.com/gemrate/v1/iconic_cards — 3 credits
GemRate's Iconic Tracker: about 100 of the most iconic sports and TCG cards, ranked, each with its combined population and gem rate across PSA, BGS, SGC and CGC, the universal grade breakdown and every grader's total, gems, grade counts, last graded and last gem date.

**Parameters:**
- `category` (string, optional) — Only this category (baseball, basketball, football, pokemon...), as the tracker labels it.
- `name` (string, optional) — Only cards whose name contains this text.
- `sort` (enum, optional, default "rank") — Row order. [one of: rank, total_desc, gems_desc, gem_rate_desc, gem_rate_asc, total_asc]
- `limit` (integer, optional, default 100) — Rows per page (1-1000).
- `page` (integer, optional, default 1) — Page of rows.

**Returns:** results[]{rank, checklist_id, year, set_name, name, card_number, parallel, category, description, total_graded, gems, gem_rate, gem_rate_percent, universal_grades[], by_grader[]{grader, total_graded, gems, gem_rate, grades[]{grade (e.g. 10, 9.5, 10 Pristine, 10 Black Label, Auth), count, universal_grade, is_gem}, last_graded, last_gem_date, ...}, collectors_note}, count, total_rows, has_more

**Example request body:**
```json
{
  "category": "baseball"
}
```

### POST https://api.reefapi.com/gemrate/v1/grading_volume — 3 credits
How many cards are being graded: total graded all time, graded yesterday and in the last 7 and 30 days against the prior period, daily average, annual pace, the same per category, daily, weekly and monthly volume, and this week's most graded players, sets and cards (sports or TCG).

**Parameters:**
- `segment` (enum, optional, default "combined") — Which top-players/sets/cards lists to return (volume figures cover every category either way). [one of: combined, sports, tcg]

**Returns:** segment, summary{date, grading_date, total_graded_all_time, graded_last_day, graded_prior_day, graded_last_7_days, graded_prior_7_days, graded_last_30_days, graded_prior_30_days, change_percent_day, change_percent_7_days, change_percent_30_days}, daily_average_past_30_days, daily_average_prior_30_days, annual_pace, by_category[]{category, …same fields}, top_players_this_week[]{name, category, graded_all_time, graded_last_week, graded_prior_week, weekly_change_percent}, top_sets_this_week[]{year, set_name, category, …}, top_cards_this_week[]{year, set_name, name, card_number, parallel, graded_all_time, gems_all_time, graded_last_week, gem_rate_all_time_percent, …}, daily[]{date, graded, total_graded_all_time}, weekly[]{week, graded}, monthly[]{month, graded}

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=gemrate
- Human docs page: https://reefapi.com/docs/gemrate
- Overview page: https://reefapi.com/gemrate-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt