> ## 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. # Cert lookup > Returns the details of a single graded card identified by its grading company and cert number. The response includes the [`gemrate_id`](/gemrate-id) of the card for reference within the GemRate system. Shared identity fields (`description`, `gemrate_id`, `universal_gemrate_id`, `is_universal_match`, `gemrate_url`, `grader`) sit at the top level; everything specific to the grading company is nested under **`grader_data`** — always `cert`, `grade`, `grade_label`, `set_url`, `has_auto_grade`, `auto_grade_label`, `population_context` and `cert_retrieval_month` (the `YYYY-MM` month which the card data was last retrieved), plus grader-specific fields. **Grader-specific fields (inside `grader_data`).** These appear only for the graders that supply them; treat a missing field as "not applicable to this grader": - **PSA** - `spec_id`: PSA's internal spec/catalog id for the card. - `population_context_auto_split`: An autographed vs. non-autographed breakdown of the within-grader population counts, sitting beside `population_context` in `grader_data`. Present only on PSA certs and always included (no `?auto_split=true` flag — that flag gates the separate, differently-shaped `auto_split` on the population endpoints). - **Beckett** - `subgrades`: An object with Beckett's four subgrades if present. **Non-standard certs.** In some cases a cert cannot be associated with a card in our system — most commonly Beckett **BCCG** — so `gemrate_id`/`universal_gemrate_id` come back `null` and `grade`/`population_context` may be null. Lean by default. Use the [population](/api-reference/certs/get-population-for-a-cert) or [image](/api-reference/certs/get-cert-images) endpoints to get those sub-resources. ## OpenAPI ````yaml /openapi.yaml get /v1/certs/{grader}/{cert} 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/certs/{grader}/{cert}: get: tags: - Certs summary: Cert lookup description: > Returns the details of a single graded card identified by its grading company and cert number. The response includes the [`gemrate_id`](/gemrate-id) of the card for reference within the GemRate system. Shared identity fields (`description`, `gemrate_id`, `universal_gemrate_id`, `is_universal_match`, `gemrate_url`, `grader`) sit at the top level; everything specific to the grading company is nested under **`grader_data`** — always `cert`, `grade`, `grade_label`, `set_url`, `has_auto_grade`, `auto_grade_label`, `population_context` and `cert_retrieval_month` (the `YYYY-MM` month which the card data was last retrieved), plus grader-specific fields. **Grader-specific fields (inside `grader_data`).** These appear only for the graders that supply them; treat a missing field as "not applicable to this grader": - **PSA** - `spec_id`: PSA's internal spec/catalog id for the card. - `population_context_auto_split`: An autographed vs. non-autographed breakdown of the within-grader population counts, sitting beside `population_context` in `grader_data`. Present only on PSA certs and always included (no `?auto_split=true` flag — that flag gates the separate, differently-shaped `auto_split` on the population endpoints). - **Beckett** - `subgrades`: An object with Beckett's four subgrades if present. **Non-standard certs.** In some cases a cert cannot be associated with a card in our system — most commonly Beckett **BCCG** — so `gemrate_id`/`universal_gemrate_id` come back `null` and `grade`/`population_context` may be null. Lean by default. Use the [population](/api-reference/certs/get-population-for-a-cert) or [image](/api-reference/certs/get-cert-images) endpoints to get those sub-resources. operationId: getCert parameters: - $ref: '#/components/parameters/Grader' - $ref: '#/components/parameters/Cert' - $ref: '#/components/parameters/ParsedDescriptionFlag' - name: psa_dna in: query description: > Set to `true` to look up a standalone PSA/DNA autograph-authentication cert — a signed item (photo, ball, cut signature, ungraded card) that PSA authenticated for the signature only and that has no card grade. These records live in PSA's autograph-authentication database, not the card-grading one. Graded autograph cards do **not** need this flag — they return on the normal lookup with their grade in `grader_data`. PSA-only; ignores the path grader. Must be `true` or `false`; any other value returns `400 invalid_parameter`. required: false schema: type: boolean responses: '200': description: The cert's details, including the card's GemRate ID. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Cert' meta: $ref: '#/components/schemas/Meta' examples: psa: summary: PSA — standard graded card (spec_id, has_auto_grade false) value: data: description: 2011 Topps Update Mike Trout Diamond Anniversary US175 universal_gemrate_id: d0719f0bc7f933c389832d01668ef5026dee09a6 gemrate_id: d0719f0bc7f933c389832d01668ef5026dee09a6 is_universal_match: true gemrate_url: >- https://gemrate.com/card/d0719f0bc7f933c389832d01668ef5026dee09a6 grader: psa grader_data: cert: '69437824' grade: psa_10 grade_label: '10' set_url: >- https://www.psacard.com/pop/baseball-cards/2011/topps-update/100690 population_context: grade_population: 366 population_higher: 0 total_population: 774 gem_total: 366 gem_rate: 0.472868 population_context_auto_split: auto: grade_population: 8 population_higher: 0 total_population: 27 grade_qualifier_population: 0 non_auto: grade_population: 358 population_higher: 0 total_population: 747 grade_qualifier_population: 0 spec_id: '1816253' qualifier_type: null has_auto_grade: false auto_grade_label: null cert_retrieval_month: 2026-07 meta: request_id: local psa_with_parsed_description: summary: PSA — standard graded card with parsed description value: data: description: 2011 Topps Update Mike Trout Diamond Anniversary US175 parsed_description: category: Baseball year: '2011' set_name: Topps Update name: Mike Trout card_number: US175 parallel: Diamond Anniversary subset: null universal_gemrate_id: d0719f0bc7f933c389832d01668ef5026dee09a6 gemrate_id: d0719f0bc7f933c389832d01668ef5026dee09a6 is_universal_match: true gemrate_url: >- https://gemrate.com/card/d0719f0bc7f933c389832d01668ef5026dee09a6 grader: psa grader_data: cert: '69437824' grade: psa_10 grade_label: '10' set_url: >- https://www.psacard.com/pop/baseball-cards/2011/topps-update/100690 population_context: grade_population: 366 population_higher: 0 total_population: 774 gem_rate: 0.472868 gem_total: 366 grade_qualifier_population: 0 population_context_auto_split: auto: grade_population: 8 population_higher: 0 total_population: 27 grade_qualifier_population: 0 non_auto: grade_population: 358 population_higher: 0 total_population: 747 grade_qualifier_population: 0 spec_id: '1816253' qualifier_type: null has_auto_grade: false auto_grade_label: null cert_retrieval_month: 2026-07 meta: request_id: local psa_autograph: summary: >- PSA graded autograph card — auto_grade_label set, returns on the normal lookup value: data: description: 1990 Topps Ken Griffey Jr 336 universal_gemrate_id: 36b5ecff59446950cad70cdec0e21776a36d155b gemrate_id: 36b5ecff59446950cad70cdec0e21776a36d155b is_universal_match: true gemrate_url: >- https://gemrate.com/card/36b5ecff59446950cad70cdec0e21776a36d155b grader: psa grader_data: cert: '52664979' grade: psa_7 grade_label: '7' set_url: >- https://www.psacard.com/pop/baseball-cards/1990/topps/49747 population_context: grade_population: 2638 population_higher: 13843 total_population: 19010 gem_total: 634 gem_rate: 0.033351 grade_qualifier_population: 0 population_context_auto_split: auto: grade_population: 5 population_higher: 16 total_population: 69 grade_qualifier_population: 0 non_auto: grade_population: 2633 population_higher: 13827 total_population: 18941 grade_qualifier_population: 0 spec_id: '204727' qualifier_type: null has_auto_grade: true auto_grade_label: GEM MT 10 cert_retrieval_month: 2026-07 meta: request_id: local psa_qualifier: summary: PSA qualifier grade — grade psa_q7, qualifier_type OC value: data: description: 1978 O-Pee-Chee Nolan Ryan 105 universal_gemrate_id: 5dc9c5aca48fcb6d9ca44f9ab78e6fdb306dd822 gemrate_id: 5dc9c5aca48fcb6d9ca44f9ab78e6fdb306dd822 is_universal_match: true gemrate_url: >- https://gemrate.com/card/5dc9c5aca48fcb6d9ca44f9ab78e6fdb306dd822 grader: psa grader_data: cert: '5076850' grade: psa_q7 grade_label: 7 (OC) set_url: >- https://www.psacard.com/pop/baseball-cards/1978/o-pee-chee/42604 population_context: grade_population: 185 population_higher: 552 total_population: 927 gem_total: 2 gem_rate: 0.002157 grade_qualifier_population: 7 population_context_auto_split: auto: grade_population: 2 population_higher: 3 total_population: 16 grade_qualifier_population: 0 non_auto: grade_population: 183 population_higher: 549 total_population: 911 grade_qualifier_population: 0 spec_id: '248367' qualifier_type: OC has_auto_grade: false auto_grade_label: null cert_retrieval_month: 2024-07 meta: request_id: local psa_dna: summary: >- PSA/DNA authentication (psa_dna=true) — signature-only record, no card grade value: data: description: Trading Card result: Authentic primary_subjects: - PETE ROSE other_subjects: [] cert_details_cached: 2024-06 meta: request_id: local beckett: summary: Beckett value: data: description: >- 2024 Dragon Ball Super Fusion World Awakened Pulse Son Goku SUPER ALT ART FOIL SCR FB01139 universal_gemrate_id: null gemrate_id: a6eec0f679c010dfbffc1ddbdc7a20de45987ef9 is_universal_match: false gemrate_url: >- https://gemrate.com/card/a6eec0f679c010dfbffc1ddbdc7a20de45987ef9 grader: beckett grader_data: cert: '20281646' grade: beckett_9_5 grade_label: '9.5' set_url: https://www.beckett.com/grading/set_match/26196502 population_context: grade_population: 173 population_higher: 246 total_population: 445 gem_total: 419 gem_rate: 0.941573 has_auto_grade: false auto_grade_label: null subgrades: centering: '9.5' corners: '10.0' edges: '10.0' surfaces: '9.5' cert_retrieval_month: 2026-07 meta: request_id: local beckett_autograph: summary: Beckett — auto-graded card, auto_grade_label and subgrades value: data: description: 2005 Playoff Contenders Aaron Rodgers AU/530* RC 101 universal_gemrate_id: c0424e66ffa6bf87d987067701c64caf340ce25b gemrate_id: 8eea9dd26e170054fde35d4cd3d386c3c61a2f45 is_universal_match: true gemrate_url: >- https://gemrate.com/card/c0424e66ffa6bf87d987067701c64caf340ce25b grader: beckett grader_data: cert: '8577513' grade: beckett_9_5 grade_label: '9.5' set_url: https://www.beckett.com/grading/set_match/2804572 population_context: grade_population: 45 population_higher: 0 total_population: 337 gem_total: 45 gem_rate: 0.133531 has_auto_grade: true auto_grade_label: '10.0' subgrades: centering: '9.5' corners: '9.0' edges: '9.5' surfaces: '9.5' cert_retrieval_month: 2026-03 meta: request_id: local beckett_partial: summary: Beckett — graded without subgrades (subgrades null) value: data: description: 2020 Bowman Prospects Bobby Witt Jr. BP25 universal_gemrate_id: 447ee2a22e82618adf4c800f4db3c3626b0936a3 gemrate_id: f8af2d9188e9ac3b48922a85e9328c810bc87367 is_universal_match: true gemrate_url: >- https://gemrate.com/card/447ee2a22e82618adf4c800f4db3c3626b0936a3 grader: beckett grader_data: cert: '18007746' grade: null grade_label: null set_url: https://www.beckett.com/grading/set_match/18323243 population_context: grade_population: null population_higher: 393 total_population: 393 gem_total: 249 gem_rate: 0.633588 has_auto_grade: false auto_grade_label: null subgrades: null cert_retrieval_month: 2026-07 meta: request_id: local sgc: summary: SGC value: data: description: 2021 Panini Mosaic Trevor Lawrence 301 universal_gemrate_id: da477dfbb661e02ccef83fadc07b8b78a2cfb3af gemrate_id: 04f5a254ca062f4708c6c1c95a567168763af5b1 is_universal_match: true gemrate_url: >- https://gemrate.com/card/da477dfbb661e02ccef83fadc07b8b78a2cfb3af grader: sgc grader_data: cert: '4132202' grade: sgc_10 grade_label: '10' set_url: >- https://gosgc.com/pop-report/result/2021%20Panini%20Mosaic/Football population_context: grade_population: 51 population_higher: 0 total_population: 182 gem_total: 51 gem_rate: 0.28022 has_auto_grade: false auto_grade_label: null cert_retrieval_month: 2023-01 meta: request_id: local sgc_autograph: summary: SGC — auto-graded card, auto_grade_label set value: data: description: >- 2020 Panini Contenders Joe Burrow Auto., Var. Playoff Ticket /49 101 universal_gemrate_id: null gemrate_id: 02484c1c8a54bf10a9bc80f1ea2d663fe6183cb7 is_universal_match: false gemrate_url: >- https://gemrate.com/card/02484c1c8a54bf10a9bc80f1ea2d663fe6183cb7 grader: sgc grader_data: cert: '0855686' grade: sgc_10 grade_label: '10' set_url: >- https://gosgc.com/pop-report/result/2020%20Panini%20Contenders/Football population_context: grade_population: 2 population_higher: 0 total_population: 4 gem_total: 2 gem_rate: 0.5 has_auto_grade: true auto_grade_label: '10' cert_retrieval_month: 2026-07 meta: request_id: local cgc: summary: CGC value: data: description: >- 1999 Base Set - Unlimited - English Charizard Rare Holo 4/102 universal_gemrate_id: ffb8699bb7f435eff4e9761f8e29358e351d777e gemrate_id: e8d1d0848b02c4392205c65034c2c83f797d30cd is_universal_match: true gemrate_url: >- https://gemrate.com/card/ffb8699bb7f435eff4e9761f8e29358e351d777e grader: cgc grader_data: cert: '3760885001' grade: cgc_8 grade_label: '8' set_url: >- https://www.cgccards.com/population-report/tcg/pokémon/2/original series/1014/base-set---unlimited---english/18936/ population_context: grade_population: 1643 population_higher: 2949 total_population: 14139 gem_total: 284 gem_rate: 0.020086 has_auto_grade: false auto_grade_label: null cert_retrieval_month: 2023-09 meta: request_id: local cgc_autograph: summary: CGC — auto-graded card, auto_grade_label set value: data: description: >- 2024 Panini Obsidian Lamine Yamal Volcanic Material Signatures VS-LY universal_gemrate_id: null gemrate_id: b972db3afe56a9033b73c4910c0563ca4fcac8ec is_universal_match: false gemrate_url: >- https://gemrate.com/card/b972db3afe56a9033b73c4910c0563ca4fcac8ec grader: cgc grader_data: cert: '6163731001' grade: cgc_8_5 grade_label: '8.5' set_url: >- https://www.cgccards.com/population-report/sports/soccer/12/2020-present/123/2024-25-panini-obsidian/48988/ population_context: grade_population: 1 population_higher: 0 total_population: 1 gem_total: 0 gem_rate: 0 auto_grade: '10' cert_retrieval_month: 2026-07 meta: request_id: local '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: We have no cert for this grader and cert number. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: cert_not_found message: No PSA cert found for cert 12345678. details: grader: psa cert: '12345678' meta: request_id: req_abc123 '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/ServerError' components: parameters: Grader: name: grader in: path required: true schema: $ref: '#/components/schemas/Grader' Cert: name: cert in: path required: true description: The cert number printed on the slab. schema: type: string example: '47178561' ParsedDescriptionFlag: name: parsed_description in: query required: false description: > When `true`, adds a `parsed_description` object that breaks the card's `description` into its catalog components for each grader (category, year, set_name, name, card_number, parallel, subset). Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean schemas: Cert: type: object description: > A single graded copy (a "cert") — lean by design. Shared identity fields sit at the top level; everything specific to the grading company that graded this copy is nested under `grader_data`. Population is NOT duplicated here; fetch it from `GET /v1/certs/{grader}/{cert}/population`. properties: description: type: string nullable: true 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 nullable: true description: > Grader-scoped card id; `null` when we cannot associate the cert with a card in our system (for example a Beckett BCCG cert) — we still return whatever cert data we have. is_universal_match: type: boolean description: >- Whether the card is universally matched (equivalent to `universal_gemrate_id` being non-null). gemrate_url: type: string description: >- Link to the card's page on gemrate.com, built from `universal_gemrate_id` (falling back to `gemrate_id`). grader: $ref: '#/components/schemas/Grader' parsed_description: allOf: - $ref: '#/components/schemas/ParsedDescription' description: Present only with `?parsed_description=true`. grader_data: $ref: '#/components/schemas/GraderData' required: - description - universal_gemrate_id - gemrate_id - is_universal_match - gemrate_url - grader - grader_data 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 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 Grader: type: string description: | The grading company. enum: - psa - beckett - sgc - cgc example: psa 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 GraderData: type: object description: > Everything specific to the grading company that graded this copy. Always carries `cert`, `grade`, `grade_label`, `set_url`, and `population_context`; the remaining fields are **grader-specific** and appear only for the graders that supply them. Treat a missing grader-specific field as "not applicable to this grader" and unknown ones as forward-compatible additions (tolerant reader). properties: cert: type: string grade: type: string nullable: true description: > The grader's label key for this cert's grade — the `{grader}_{grade}` lookup key from the grade map's `grader_labels` (e.g. `psa_10`, `beckett_9_5`). `null` when we cannot map the cert to a grade in our system (e.g. an unsupported BCCG cert). example: beckett_9_5 grade_label: type: string nullable: true description: >- The grader-native display label for the grade (e.g. `"9.5"`). `null` when the grade is unmapped. example: '9.5' set_url: type: string format: uri nullable: true description: >- The grader's pop-report URL for this card's set. `null` when unavailable. population_context: $ref: '#/components/schemas/PopulationContext' population_context_auto_split: type: object description: > **PSA only.** The autographed vs. non-autographed split of this cert's within-grader `population_context`, sitting beside it in `grader_data`. Always included on PSA certs whose context is populated — it needs **no** `?auto_split=true` flag, and is deliberately named apart from the population endpoints' opt-in `by_grader.psa.auto_split` (which carries a different, fuller shape). Each sub-block carries only the count triplet (`grade_population`/`population_higher`/`total_population`/`grade_qualifier_population`), zero-filled when the card has no autographed grades. Absent for non-PSA graders and when the context itself is unavailable (all counts `null`). properties: auto: type: object description: Autographed copies' counts. properties: grade_population: type: integer population_higher: type: integer total_population: type: integer grade_qualifier_population: type: integer non_auto: type: object description: Non-autographed copies' counts. properties: grade_population: type: integer population_higher: type: integer total_population: type: integer grade_qualifier_population: type: integer spec_id: type: string nullable: true description: '**PSA only.** The grader''s spec/catalog id for this card.' has_auto_grade: type: boolean description: > **PSA / Beckett / SGC / CGC.** `true` when the grader assigned an autograph grade to this card. The upstream data does not indicate whether a card is autographed — or whether an autograph is verified by the grader — unless the autograph itself is graded, so this reflects only whether a graded autograph is present. auto_grade_label: type: string nullable: true description: > **PSA / Beckett / SGC / CGC.** The grader's autograph grade, surfaced as a string when `has_auto_grade` is `true`; `null` otherwise. No format guarantee beyond it being a string. subgrades: allOf: - $ref: '#/components/schemas/BeckettSubgrades' nullable: true description: > **Beckett only.** Present when a Beckett card has subgrades. Not every Beckett card does — BCCG issues none, and some core-Beckett grades have none — so this is `null` when there are no subgrades. cert_retrieval_month: type: string nullable: true description: > The month (`YYYY-MM`) we last fetched this cert live from the grader. Everything in `grader_data` reflects that fetch. `null` when we have no live-fetch date on record. example: 2026-07 required: - cert - grade - grade_label - set_url - population_context 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 PopulationContext: type: object description: > This cert's population context **within its own grader**, computed on that grader's own grade ladder: how many copies sit at this grade, how many grade higher, and the grader's gem totals. Every field is `null` when the grader's population for this card is unavailable (e.g. an unsupported cert, or a total population of 0). properties: grade_population: type: integer nullable: true population_higher: type: integer nullable: true total_population: type: integer nullable: true gem_total: type: integer nullable: true gem_rate: type: number nullable: true description: Gem rate for this grader, rounded to 6 decimals. grade_qualifier_population: type: integer nullable: true description: >- The number of qualifier grades at this grade. PSA only. Qualifier grades are not included in the other population context calculations. BeckettSubgrades: type: object description: > A Beckett card's per-attribute subgrades. Each value is the grader-native grade string (e.g. `"9.5"`), or `null` for an individual attribute Beckett did not assign. Beckett only. properties: centering: type: string nullable: true example: '9.5' corners: type: string nullable: true example: '10.0' edges: type: string nullable: true example: '10.0' surfaces: type: string nullable: true example: '9.5' 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 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 ````