> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gemrate.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Get population history for a card
> Historical data access not included in basic plans. Contact GemRate for more information. Returns a card's population by grader over time. Population history data is available at daily granularity and begins on Jan 1, 2022. Data is updated once per day approximately between 16:00 and 20:00 UTC.
All card grading dates are the UTC date the population change was recorded; typically the day after grading. The `window.as_of` property returns the latest date for which population data has been recorded.
Returns every grader's series over a trailing three-year window anchored at the latest recorded date (`window.as_of`), stepping back by `interval`. The `population.window` echoes the resolved grid.
## OpenAPI
````yaml /openapi.yaml get /v1/cards/{gemrate_id}/population/history
openapi: 3.0.3
info:
title: GemRate API
version: '1.0'
description: >
The GemRate API gives you programmatic access to graded trading-card data:
look up a specific cert, get population reports and their history, look up
and search for cards, and download bulk catalogs.
## Quickstart
1. **Get an API key.** Contact the GemRate team to request one. 2. **Send it
on every request** in the `x-api-key` header. 3. **Make a call:**
```bash curl https://api.gemrate.com/v1/certs/psa/47178561 \
-H "x-api-key: YOUR_API_KEY"
```
```json {
"data": {
"description": "1986 Fleer Michael Jordan 57",
"universal_gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
"gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
"is_universal_match": true,
"gemrate_url": "https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242",
"grader": "psa",
"grader_data": {
"cert": "47178561",
"grade": "psa_5",
"grade_label": "5",
"set_url": "https://www.psacard.com/pop/basketball-cards/1986/fleer/36766",
"population_context": {
"grade_population": 2080,
"population_higher": 22520,
"total_population": 30810,
"gem_total": 340,
"gem_rate": 0.011
},
"spec_id": "299576"
}
},
"meta": { "request_id": "req_abc123" }
} ```
Shared identity fields sit at the top level; everything specific to the
grading company (grade, links, and grader-specific extras) is nested under
`grader_data`.
A cert is a specific graded copy of a card; the `gemrate_id` in the response
points to that card, which you can then explore via the `/v1/cards`
endpoints.
## Base URL
All routes live under the `/v1` version prefix:
``` https://api.gemrate.com/v1 ```
All endpoints are served over HTTPS. Reads are `GET` requests. The contract
evolves additive-only within `v1`; a genuinely incompatible change would
ship as a parallel `/v2`.
## Authentication
Pass your key in the `x-api-key` header on every request:
``` x-api-key: YOUR_API_KEY ```
- Missing or invalid key → `401`. - Valid key without access to a resource →
`403`.
## Response shape
Every successful response is an object with two top-level keys:
- `data` — the result (an object, or an array for list endpoints). - `meta`
— metadata, always including a `request_id` you can quote in
support requests.
```json { "data": { }, "meta": { "request_id": "req_abc123" } } ```
## Lean payloads and sub-resources
Cert and spec lookups return a lean default payload (identity only). Heavier
data lives on dedicated sub-resource endpoints — population and images each
have their own URL:
```bash curl "https://api.gemrate.com/v1/certs/psa/47178561/population" \
-H "x-api-key: YOUR_API_KEY"
```
## Errors
Errors return a non-2xx status and a body with a stable, machine-readable
`code` you can branch on (the `message` is for humans and may change):
```json {
"error": {
"code": "cert_not_found",
"message": "No PSA cert found for cert 12345678.",
"details": { "grader": "psa", "cert": "12345678" }
},
"meta": { "request_id": "req_abc123" }
} ```
| Status | When | |--------|------| | `200` | Success (including an empty
list — `data: []`). | | `202` | Accepted, but still processing — retry
shortly. | | `400` | Your request was malformed or invalid. | | `401` |
Missing or invalid API key. | | `403` | Your key isn't allowed to access
this resource. | | `404` | The specific item you asked for doesn't exist in
our data. | | `429` | You've hit the rate limit — slow down. | | `500` |
Something went wrong on our end. |
## Conventions
- JSON field and query-parameter names use `snake_case`. - Dates are
`YYYY-MM-DD`; timestamps are ISO-8601 UTC. - Booleans in the query string
are the strings `true` / `false`.
servers:
- url: https://api.gemrate.com
description: Production
security:
- ApiKeyAuth: []
tags:
- name: Cards
description: >-
The card itself (one gemrate_id) — its population, history, search, and
the population change feed.
- name: Certs
description: A specific graded copy of a card, identified by grader and cert number.
- name: Specs
description: A grading company's catalog entry for a card; resolves to the card.
- name: Catalogs
description: Bulk CSV downloads of graded-card data.
- name: Grades
description: The grade map — each grade's per-grader label keys and display names.
paths:
/v1/cards/{gemrate_id}/population/history:
get:
tags:
- Cards
summary: Get population history for a card
description: >
Historical data access not included in basic plans. Contact
GemRate for more information. Returns a card's population by
grader over time. Population history data is available at daily
granularity and begins on Jan 1, 2022. Data is updated once per day
approximately between 16:00 and 20:00 UTC.
All card grading dates are the UTC date the population change was
recorded; typically the day after grading. The `window.as_of` property
returns the latest date for which population data has been recorded.
Returns every grader's series over a trailing three-year window anchored
at the latest recorded date (`window.as_of`), stepping back by
`interval`. The `population.window` echoes the resolved grid.
operationId: getCardHistory
parameters:
- $ref: '#/components/parameters/GemrateId'
- name: interval
in: query
required: false
description: Sampling cadence over the trailing three-year window.
schema:
type: string
enum:
- week
- two_week
default: two_week
responses:
'200':
description: The card's per-grader population history.
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PopulationHistory'
meta:
$ref: '#/components/schemas/Meta'
example:
data:
description: 1986 Fleer Michael Jordan Base 57
universal_gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242
gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242
is_universal_match: true
gemrate_url: >-
https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242
population:
graders_included:
- psa
- beckett
- sgc
- cgc
graders:
psa:
gemrate_id: 25b4432f12a5d6ec29a6f00490200416d5dfa242
spec_id: '299576'
set_url: >-
https://www.psacard.com/pop/basketball-cards/1986/fleer/36766
beckett:
gemrate_id: 7a70aeda7692bf7c24a1b8def12e5afed61c5761
set_url: https://www.beckett.com/grading/set_match/3022391
sgc:
gemrate_id: 33a95ad34c7e119fd4a3fd6235019d1893feb630
set_url: >-
https://gosgc.com/pop-report/result/1986-87%20Fleer/Basketball
cgc:
gemrate_id: 408287c2bd6c833dde92eb99662064a9f65afbbf
set_url: >-
https://www.cgccards.com/population-report/sports/basketball/3/1980s/32/1986-87-fleer/26933/
window:
mode: trailing
interval: day
as_of: '2026-06-24'
start: '2026-06-17'
end: '2026-06-24'
points: 8
lookback: 7 day
population_data:
total: 30814
gem_total: 340
gem_rate: 0.011
data_last_updated: '2026-06-24'
last_population_change: '2026-06-24'
by_grader:
psa:
total: 30814
gem_total: 340
gem_rate: 0.011
last_population_change: '2026-06-24'
history:
- date: '2026-06-17'
total: 30793
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 453
psa_1_5: 169
psa_2: 532
psa_2_5: 57
psa_3: 940
psa_3_5: 78
psa_4: 1720
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3240
psa_6_5: 217
psa_7: 5102
psa_7_5: 323
psa_8: 9334
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-18'
total: 30795
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 453
psa_1_5: 169
psa_2: 532
psa_2_5: 57
psa_3: 941
psa_3_5: 78
psa_4: 1720
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3240
psa_6_5: 217
psa_7: 5102
psa_7_5: 323
psa_8: 9335
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-19'
total: 30803
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 533
psa_2_5: 57
psa_3: 941
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3242
psa_6_5: 217
psa_7: 5103
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-20'
total: 30804
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 533
psa_2_5: 57
psa_3: 942
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3242
psa_6_5: 217
psa_7: 5103
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-21'
total: 30804
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 533
psa_2_5: 57
psa_3: 942
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3242
psa_6_5: 217
psa_7: 5103
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-22'
total: 30804
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 533
psa_2_5: 57
psa_3: 942
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2079
psa_5_5: 161
psa_6: 3242
psa_6_5: 217
psa_7: 5103
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3078
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-23'
total: 30814
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 534
psa_2_5: 57
psa_3: 943
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2080
psa_5_5: 161
psa_6: 3244
psa_6_5: 217
psa_7: 5107
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3079
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
- date: '2026-06-24'
total: 30814
gem_total: 340
gem_rate: 0.011
grades:
psa_auth: 993
psa_1: 454
psa_1_5: 169
psa_2: 534
psa_2_5: 57
psa_3: 943
psa_3_5: 78
psa_4: 1722
psa_4_5: 126
psa_5: 2080
psa_5_5: 161
psa_6: 3244
psa_6_5: 217
psa_7: 5107
psa_7_5: 323
psa_8: 9336
psa_8_5: 713
psa_9: 3079
psa_10: 340
qualifiers:
psa_q1: 13
psa_q1_5: 4
psa_q2: 4
psa_q3: 2
psa_q4: 9
psa_q5: 7
psa_q6: 8
psa_q7: 62
psa_q8: 635
psa_q9: 394
beckett:
total: 14942
gem_total: 0
gem_rate: 0
last_population_change: '2026-06-24'
history:
- date: '2026-06-17'
total: 14938
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3308
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-18'
total: 14939
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3309
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-19'
total: 14939
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3309
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-20'
total: 14939
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3309
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-21'
total: 14939
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3309
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-22'
total: 14939
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3309
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-23'
total: 14940
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1901
beckett_8: 2723
beckett_8_5: 3310
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
- date: '2026-06-24'
total: 14942
gem_total: 554
gem_rate: 0.0371
grades:
beckett_1: 10
beckett_1_5: 42
beckett_2: 61
beckett_2_5: 91
beckett_3: 136
beckett_3_5: 180
beckett_4: 299
beckett_4_5: 262
beckett_5: 349
beckett_5_5: 405
beckett_6: 576
beckett_6_5: 818
beckett_7: 1279
beckett_7_5: 1902
beckett_8: 2724
beckett_8_5: 3310
beckett_9: 1944
beckett_9_5: 548
beckett_10_pristine: 6
beckett_10_black: 0
sgc:
total: 4498
gem_total: 0
gem_rate: 0
last_population_change: '2026-06-24'
history:
- date: '2026-06-17'
total: 4495
gem_total: 29
gem_rate: 0.0065
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 215
sgc_4_5: 126
sgc_5: 312
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-18'
total: 4496
gem_total: 29
gem_rate: 0.0065
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 312
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-19'
total: 4497
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-20'
total: 4497
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-21'
total: 4497
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-22'
total: 4497
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-23'
total: 4497
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 505
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
- date: '2026-06-24'
total: 4498
gem_total: 29
gem_rate: 0.0064
grades:
sgc_auth: 740
sgc_1: 46
sgc_1_5: 29
sgc_2: 52
sgc_2_5: 39
sgc_3: 139
sgc_3_5: 43
sgc_4: 216
sgc_4_5: 126
sgc_5: 313
sgc_5_5: 182
sgc_6: 383
sgc_6_5: 192
sgc_7: 476
sgc_7_5: 312
sgc_8: 506
sgc_8_5: 406
sgc_9: 236
sgc_9_5: 33
sgc_10: 28
sgc_10_pristine: 1
cgc:
total: 187
gem_total: 0
gem_rate: 0
last_population_change: '2026-06-24'
history:
- date: '2026-06-17'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-18'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-19'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-20'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-21'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-22'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-23'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
- date: '2026-06-24'
total: 187
gem_total: 1
gem_rate: 0.0053
grades:
cgc_auth_altered: 0
cgc_auth: 5
cgc_1: 4
cgc_1_5: 5
cgc_2: 2
cgc_2_5: 1
cgc_3: 7
cgc_3_5: 3
cgc_4: 6
cgc_4_5: 2
cgc_5: 14
cgc_5_5: 3
cgc_6: 16
cgc_6_5: 13
cgc_7: 12
cgc_7_5: 16
cgc_8: 18
cgc_8_5: 14
cgc_9: 9
cgc_9_5: 2
cgc_10: 1
cgc_10_pristine: 0
cgc_10_perfect: 0
meta:
request_id: local
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
components:
parameters:
GemrateId:
name: gemrate_id
in: path
required: true
description: >-
GemRate's universal identifier for a card (returned by cert and spec
lookups).
schema:
type: string
example: 25b4432f12a5d6ec29a6f00490200416d5dfa242
schemas:
PopulationHistory:
type: object
description: >
A card's per-grader population time series. At the top level, it carries
identity information for the card. Then a `population` with
`graders_included`, a per-grader `graders` identity object, the resolved
`window`. Lastly a `population_data` block with overall stats then a
`by_grader` entry for each grader with top-level stats and a `history`
series.
properties:
description:
type: string
universal_gemrate_id:
type: string
nullable: true
description: >-
The universal card id; always present, `null` if the card is not
universally matched.
gemrate_id:
type: string
is_universal_match:
type: boolean
description: >-
Whether the card is universally matched (equivalent to
`universal_gemrate_id` being non-null).
population:
type: object
properties:
graders_included:
type: array
description: >-
The graders present in `population_data.by_grader` (those with
population data for this card).
items:
$ref: '#/components/schemas/Grader'
graders:
type: object
description: >
Static per-grader identity, keyed by grader id. Each grader's
own `gemrate_id`, `spec_id`, `set_url`, and — with
`?parsed_description=true` — that grader's `parsed_description`.
additionalProperties:
$ref: '#/components/schemas/GraderMeta'
window:
$ref: '#/components/schemas/HistoryWindow'
population_data:
$ref: '#/components/schemas/HistoryPopulationData'
required:
- graders_included
- graders
- window
- population_data
required:
- description
- universal_gemrate_id
- gemrate_id
- is_universal_match
- population
Meta:
type: object
description: Metadata attached to every response.
properties:
request_id:
type: string
description: A unique ID for this request; quote it in support requests.
example: req_abc123
required:
- request_id
Grader:
type: string
description: |
The grading company.
enum:
- psa
- beckett
- sgc
- cgc
example: psa
GraderMeta:
type: object
description: >
Static identity for one grader's series — the non-count fields the
population endpoint carries per grader. `gemrate_id` is the grader's own
id (its universal-member id on a universal card).
properties:
gemrate_id:
type: string
spec_id:
type: string
nullable: true
set_url:
type: string
format: uri
nullable: true
parsed_description:
allOf:
- $ref: '#/components/schemas/ParsedDescription'
description: >
Present only with `?parsed_description=true` — this grader's own
descriptor broken into catalog components.
required:
- gemrate_id
- spec_id
- set_url
HistoryWindow:
type: object
description: >
Echoes the resolved sampling grid so a client knows exactly what it got.
`start`/`end` are the oldest/newest grid dates; `as_of` is the latest
population run date that anchors "today". The grid is always a trailing
three-year window sampled at the requested `interval`.
properties:
interval:
type: string
enum:
- week
- two_week
lookback:
type: string
enum:
- 3 year
as_of:
type: string
format: date
start:
type: string
format: date
end:
type: string
format: date
points:
type: integer
description: Number of grid points per grader.
required:
- mode
- interval
- as_of
- start
- end
- points
HistoryPopulationData:
type: object
description: >
The history endpoint's counts payload — cross-grader current scalar
totals and a `by_grader` map whose entries each carry their current
totals plus a `history` series (in place of the card endpoint's static
`grades`/`qualifiers`).
properties:
total:
type: integer
gem_total:
type: integer
gem_rate:
type: number
data_last_updated:
type: string
nullable: true
description: >
The dataset's global last-updated marker — the newest
`last_population_change` across the whole population collection. The
same for every card; distinct from this card's own
`last_population_change`.
last_population_change:
type: string
nullable: true
by_grader:
type: object
description: >-
Per-grader current totals + series keyed by grader id (`psa`,
`beckett`, `sgc`, `cgc`).
additionalProperties:
$ref: '#/components/schemas/GraderHistory'
required:
- total
- gem_total
- gem_rate
- by_grader
Error:
type: object
properties:
error:
type: object
properties:
code:
$ref: '#/components/schemas/ErrorCode'
message:
type: string
description: A human-readable description. May change; don't parse it.
details:
type: object
description: Optional structured context about the error.
additionalProperties: true
required:
- code
- message
meta:
$ref: '#/components/schemas/Meta'
required:
- error
ParsedDescription:
type: object
description: >
A card's `description` broken into its catalog components. Returned only
when `?parsed_description=true`.
properties:
category:
type: string
nullable: true
year:
type: string
nullable: true
set_name:
type: string
nullable: true
name:
type: string
nullable: true
card_number:
type: string
nullable: true
parallel:
type: string
nullable: true
subset:
type: string
nullable: true
GraderHistory:
type: object
description: >
One grader's entry inside `population_data.by_grader` on the history
endpoint — the grader's current scalar totals plus its sampled `history`
series (oldest point first). The per-date grade breakdowns live inside
each history point.
properties:
total:
type: integer
gem_total:
type: integer
gem_rate:
type: number
last_population_change:
type: string
nullable: true
history:
type: array
description: The grader's resampled time series, oldest point first.
items:
$ref: '#/components/schemas/HistoryPoint'
required:
- total
- gem_total
- gem_rate
- history
ErrorCode:
type: string
description: >-
A stable, machine-readable error code. Branch on this. Tolerate new
values.
enum:
- invalid_grader
- invalid_cert
- invalid_parameter
- invalid_date_range
- cert_not_found
- card_not_found
- spec_not_found
- unauthorized
- forbidden
- rate_limited
- processing
- internal_error
HistoryPoint:
type: object
description: >
One sampled datapoint in a grader's population series, with
`grades`/`qualifiers` keyed by that grader's own label keys. The series
is resampled onto a shared date grid (see the endpoint), so a point
carries forward the most recent change at or before its `date`. Grid
dates that precede the grader's first recorded population are **null
entries** — `total`, `grades`, `gem_total`, and `gem_rate` are `null`.
properties:
date:
type: string
format: date
example: '2024-01-01'
total:
type: integer
nullable: true
description: null before the grader's first recorded population.
grades:
allOf:
- $ref: '#/components/schemas/GradeCounts'
nullable: true
description: >-
The grader's per-grade counts for this point; `null` on a
pre-history entry.
gem_total:
type: integer
nullable: true
description: >
The grader's gem-tier grades (e.g. `psa_10`;
`cgc_10`/`_pristine`/`_perfect`) summed for this point. `null` on a
pre-history entry.
gem_rate:
type: number
nullable: true
description: >
`gem_total / total` for this point, rounded to 4 decimals (0 when
`total` is 0). `null` on a pre-history entry.
qualifiers:
allOf:
- $ref: '#/components/schemas/Qualifiers'
description: PSA only — the qualifier axis. Absent for graders without one.
auto_split:
type: object
description: >
PSA-only autographed/non-autographed split for this point, added
with `?auto_split=true`. Both sub-blocks are zero-filled when the
point has no autographed grades, so it is always present on a real
datapoint (never null); it is omitted on pre-history entries (those
with `total: null`). Each breakdown carries raw per-date counts only
— `grades` and `qualifiers`, no `total`/`gem_total`/`gem_rate`.
properties:
auto:
$ref: '#/components/schemas/HistoryBreakdown'
non_auto:
$ref: '#/components/schemas/HistoryBreakdown'
partial:
type: boolean
description: >
Present and `true` only on a fixed-mode `end` point that didn't land
on a `interval` step (a shorter-than-`interval` final interval).
Absent otherwise.
required:
- date
GradeCounts:
type: object
description: >
Population counts keyed by the grader's **label keys**
(`{grader}_{grade}`, e.g. `psa_8`, `psa_10`, `beckett_9_5`,
`cgc_10_perfect`).
additionalProperties:
type: integer
example:
psa_8: 21073
psa_9: 50741
psa_10: 156
Qualifiers:
type: object
nullable: true
description: >
PSA-only qualifier counts keyed by the grader's qualifier label keys
(`psa_q1`, `psa_q1_5`, `psa_q2`…`psa_q9`). `null` for graders with no
qualifier axis (beckett, sgc, cgc).
additionalProperties:
type: integer
example:
psa_q8: 30
psa_q9: 75
HistoryBreakdown:
type: object
description: >-
A per-date raw split of a history point's population (grades +
qualifiers only).
properties:
grades:
$ref: '#/components/schemas/GradeCounts'
qualifiers:
$ref: '#/components/schemas/Qualifiers'
responses:
BadRequest:
description: Your request was malformed or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: invalid_grader
message: Unknown grader 'foo'.
meta:
request_id: req_abc123
Unauthorized:
description: Missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: unauthorized
message: Missing or invalid API key.
meta:
request_id: req_abc123
Forbidden:
description: Your key isn't allowed to access this resource.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: forbidden
message: Your key does not have access to this resource.
meta:
request_id: req_abc123
NotFound:
description: The specific item you asked for doesn't exist in our data.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
RateLimited:
description: You've hit the rate limit — slow down.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: rate_limited
message: Too many requests.
meta:
request_id: req_abc123
ServerError:
description: Something went wrong on our end.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
code: internal_error
message: Something went wrong.
meta:
request_id: req_abc123
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````