---
title: "Get Population Data by Certificate Number (GemRate Contract Required)"
method: POST
path: "/v1/cards/population-by-cert"
tags: ["GemRate Population"]
---

# Get Population Data by Certificate Number (GemRate Contract Required)

`POST /v1/cards/population-by-cert`

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/population-by-cert`
- Auth: API key in header `X-API-Key`

Resolves a grader certificate to its card, then returns the full GemRate population report. Adds a `cert` block giving the queried slab's own grade and its position in the population.

**This endpoint is available only to commercial customers with their own GemRate contract.** GemRate population data is licensed, so Card Hedge cannot serve it to customers who do not hold a contract with GemRate directly.

Access requires an Enterprise-tier API key with GemRate access explicitly enabled on it. Every other request — including Enterprise keys that have not been enabled — receives a 403 Forbidden response. Contact support@cardhedger.com to have GemRate access enabled once your GemRate contract is in place.

**Daily allowance of uncached lookups.** The first time a certificate is looked up it needs a live call to our grading-data provider and draws on your account's daily allowance of such lookups; repeat lookups are served from cache and do not. See *Rate limits* in the API overview for your tier's allowance.

## Request body

- PopulationByCertRequest: Look up population by grader certificate number.
  - `cert` string, required: Certificate number
  - `grader` string: Grading company (defaults to PSA)

## Response `200`

Successful Response

- PopulationResponse: Normalized GemRate population report.
  - `gemrate_id` string, required
  - `universal_gemrate_id` string, nullable
  - `description` string, nullable
  - `population_type` string, nullable
  - `as_of` string, nullable: GemRate report date
  - `last_population_change` string, nullable
  - `card` PopulationCard: Card identity as GemRate describes it.
    - `category` string, nullable
    - `year` string, nullable
    - `set_name` string, nullable
    - `player` string, nullable
    - `parallel` string, nullable
    - `card_number` string, nullable
  - `totals` PopulationTotals: Universal totals across every grader in the report.
    - `total_population` integer, nullable
    - `total_gems_or_greater` integer, nullable
    - `gem_rate` number, nullable: total_gems_or_greater / total_population, 4dp
  - `graders` PopulationGrader[]
    - `grader` string, required: Grader code, e.g. "PSA", "BGS"
    - `specid` string, nullable: Grader-internal spec ID
    - `set_url` string, nullable: Grader's pop-report URL
    - `total_population` integer, nullable: Total slabs graded by this grader
    - `gems` integer, nullable: Gem-or-better count
    - `gem_rate` number, nullable: gems / total_population
    - `grades` PopulationGradeRow[]: Non-zero grades, ascending. Zero rows are omitted.
      - `grade` string, required: CardHedge grade label, e.g. "PSA 10"
      - `count` integer, required: Total population at this grade
      - `non_auto` integer: Population excluding autographed slabs
      - `auto` integer: Population of autographed slabs only
      - `qualifiers` integer: Slabs graded with a qualifier
  - `cert` PopulationCertInfo: The queried slab's own position in the population. Only present on population-by-cert.
    - `grader` string, required
    - `cert` string, required
    - `grade` string, nullable: CardHedge grade label
    - `grade_population` integer, nullable: Population at this slab's grade
    - `population_higher` integer, nullable: Population graded higher than this slab

## Other responses

- `403`: Not available on this API key. GemRate population data is restricted to commercial customers holding their own GemRate contract, on an Enterprise key with GemRate access enabled.
- `404`: Certificate not found in the GemRate database.
- `422`: Validation Error
- `429`: Daily allowance of uncached certificate lookups used up. Each account may look up a limited number of certificates not seen before per day; certificates already looked up are still served from cache. Resets at 00:00 UTC; see the `Retry-After` and `X-RateLimit-*` headers. Batch endpoints return this only when no certificate in the batch could be served; otherwise they mark unserved certificates with `error: gemrate_daily_quota_exceeded`. Contact sales at support@cardhedger.com for a higher allowance.
- `502`: GemRate upstream unavailable.

## Changes

- **2026-10-05** `a7e88a62d4ba`: 1 info
  - added the non-success response with the status `429`

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/population-by-cert/post.md)

---

[API](https://skmtc.dev/cardhedger/apis/card-hedge-api.md) - [All operations](https://skmtc.dev/cardhedger/apis/card-hedge-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardhedger/apis/card-hedge-api/revisions/6de42f192a4d?raw)