---
title: "Get Population Data by GemRate ID (GemRate Contract Required)"
method: POST
path: "/v1/cards/population-by-gemrate-id"
tags: ["GemRate Population"]
---

# Get Population Data by GemRate ID (GemRate Contract Required)

`POST /v1/cards/population-by-gemrate-id`

## Request

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

Returns the full GemRate population report for a card: per-grader counts at every grade, split by autographed vs non-autographed, plus universal cross-grader totals and gem rate.

**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.

## Request body

- PopulationByGemrateIdRequest: Look up population by GemRate ID.
  - `gemrate_id` string, required: GemRate ID (grader-specific or universal)

## 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`: GemRate ID not found.
- `422`: Validation Error
- `502`: GemRate upstream unavailable.

---

[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)