> ## 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 for a cert > Returns the lean cert (the same shape as [`GET /v1/certs/{grader}/{cert}`](/api-reference/certs/cert-lookup), including `grader_data` with its within-grader `population_context`) plus a top-level `population` block for the card this cert is a copy of. Same population data as [`GET /v1/cards/{id}/population`](/api-reference/cards/get-population-for-a-card), reached from a cert instead of a GemRate ID. `population` is `null` when the cert is known but not yet linked to a card entity. ## OpenAPI ````yaml /openapi.yaml get /v1/certs/{grader}/{cert}/population 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}/population: get: tags: - Certs summary: Get population for a cert description: > Returns the lean cert (the same shape as [`GET /v1/certs/{grader}/{cert}`](/api-reference/certs/cert-lookup), including `grader_data` with its within-grader `population_context`) plus a top-level `population` block for the card this cert is a copy of. Same population data as [`GET /v1/cards/{id}/population`](/api-reference/cards/get-population-for-a-card), reached from a cert instead of a GemRate ID. `population` is `null` when the cert is known but not yet linked to a card entity. operationId: getCertPopulation parameters: - $ref: '#/components/parameters/Grader' - $ref: '#/components/parameters/Cert' - $ref: '#/components/parameters/AutoFlag' - $ref: '#/components/parameters/AllGradersFlag' - $ref: '#/components/parameters/ParsedDescriptionFlag' responses: '200': description: >- The cert's card population, plus the cert's within-grader context inside `grader_data`. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CertPopulation' meta: $ref: '#/components/schemas/Meta' example: 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' cert_retrieval_month: 2026-07 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/ population_data: total: 50437 gem_total: 924 gem_rate: 0.0183 data_last_updated: '2026-06-24' last_population_change: '2026-06-24' by_grader: psa: total: 30810 gem_total: 340 gem_rate: 0.011 last_population_change: '2026-06-24' 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: 0 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: 554 gem_rate: 0.0371 last_population_change: '2026-06-24' 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: 29 gem_rate: 0.0064 last_population_change: '2026-06-24' 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: 1 gem_rate: 0.0053 last_population_change: '2026-06-24' grades: cgc_auth_altered: 34 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': 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' AutoFlag: name: auto_split in: query required: false description: > When true, adds a PSA-only auto_split object ({auto, non_auto} breakdowns) to the PSA `population_data.by_grader.psa` block. Its sub-blocks are zero-filled when the card has no PSA autographed grades (the object itself is always present when the flag is set). Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean AllGradersFlag: name: all_graders in: query required: false description: > Defaults to `true` — the `population` block covers every grader the card has. Set `false` to restrict it to the grader that owns this cert/spec (the `{grader}` path segment): `by_grader` then holds only that grader and the top-level `total`/`gem_total`/`gem_rate` reflect it alone. Must be `true` or `false`; any other value returns `400 invalid_parameter`. schema: type: boolean default: true 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: CertPopulation: description: > The lean cert (same shape as `GET /v1/certs/{grader}/{cert}`, including `grader_data`) plus a top-level `population` block for the card this cert is a copy of — the identical `population` block shape as the card and spec-population endpoints. The cert's own within-grader `population_context` stays inside `grader_data`. `population` is `null` when the cert is known but not yet linked to a card entity. allOf: - $ref: '#/components/schemas/Cert' - type: object properties: population: allOf: - $ref: '#/components/schemas/CardPopulation' nullable: true required: - 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 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 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 CardPopulation: type: object description: > The `population` block, shared by the card, spec-population, and cert-population endpoints. Wraps `graders_included`, a per-grader `graders` identity object, and the `population_data` counts payload. properties: graders_included: type: array items: $ref: '#/components/schemas/Grader' description: The graders present in `graders` / `population_data.by_grader`. graders: type: object description: > Static per-grader identity keyed by grader id — each grader's `gemrate_id`, `spec_id`, `set_url`, and (with `?parsed_description=true`) its own `parsed_description`. additionalProperties: $ref: '#/components/schemas/GraderMeta' population_data: $ref: '#/components/schemas/PopulationData' required: - graders_included - graders - population_data 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 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 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 PopulationData: type: object description: > The counts payload inside a `population` block. `total`/`gem_total`/`gem_rate` are scalar sums across all graders; the per-grade breakdown lives under each `by_grader` entry, keyed by that grader's own label keys. Per-grader identity (`spec_id`/`set_url`/…) lives in the sibling `graders` object, not here. 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 counts keyed by grader id (`psa`, `beckett`, `sgc`, `cgc`). additionalProperties: $ref: '#/components/schemas/GraderBreakdown' required: - total - gem_total - gem_rate - by_grader 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' GraderBreakdown: description: > One grader's counts inside `population_data.by_grader` — a `PopulationBreakdown` plus that grader's own `last_population_change`. Counts only; identity lives in the sibling `graders` object. allOf: - type: object properties: total: type: integer gem_total: type: integer gem_rate: type: number last_population_change: type: string nullable: true grades: $ref: '#/components/schemas/GradeCounts' qualifiers: $ref: '#/components/schemas/Qualifiers' auto_split: type: object description: > **PSA only.** Autographed/non-autographed split of this grader's counts, added to the `by_grader.psa` entry with `?auto_split=true`. Both sub-blocks are zero-filled when the card has no autographed grades (the object itself is always present when the flag is set). Absent for other graders and when the flag is not set. properties: auto: allOf: - $ref: '#/components/schemas/PopulationBreakdown' description: Autographed copies' breakdown. non_auto: allOf: - $ref: '#/components/schemas/PopulationBreakdown' description: Non-autographed copies' breakdown. 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 PopulationBreakdown: type: object description: >- A population breakdown keyed by a grader's label keys (the PSA `auto_split` sub-blocks share this shape). properties: total: type: integer gem_total: type: integer description: Count at this grader's gem tiers (gem mint and above). gem_rate: type: number 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 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 ````