---
title: "Get Price History by Certificate Number"
method: POST
path: "/v1/cards/prices-by-cert"
tags: ["Pricing & Valuations"]
---

# Get Price History by Certificate Number

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

## Request

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

Get card information and pricing by grader certificate number.

This endpoint performs a multi-step lookup:
1. Checks the persistent validated-certificate cache; queries GemRate only
   when that certificate has not been successfully retrieved before
2. Fetches card details from CardHedge using GemRate IDs
3. Fallback: if step 2 finds no card, matches the GemRate description
   against the AI `card-match` endpoint
4. Retrieves price history for the card at the specified grade, served
   from the synced `card_prices` table with upstream fallback for cards
   the sync does not cover

**Related:** to look up many certificates at once, use `details-by-certs`
(card details only) or `batch-prices-by-cert` (one price estimate per cert
instead of price history).

`card_source` reports how the card was resolved -- `gemrate_id` for the
direct GemRate ID lookup, or `card_match` for the description fallback.
When the fallback is used, `match_confidence` carries the AI match score
(0-1); treat prices derived from a low-confidence match with care. Cards
resolved via the `card_match` fallback have null `category_group` and
`set_type` -- the matcher does not return those two fields.

**Example curl:**
```bash
# Default: 180 days of price history
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "cert": "76676185",
       "grader": "PSA"
     }' \
     "https://api.cardhedger.com/v1/cards/prices-by-cert"

# Custom: 30 days of price history
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "cert": "76676185",
       "grader": "PSA",
       "days": 30
     }' \
     "https://api.cardhedger.com/v1/cards/prices-by-cert"
```

Returns certificate info, card details, and price history (default: 180 days, max: 365 days).

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

- CertLookupRequest: Request parameters for certificate lookup endpoint.
  - `cert` string, required: Certificate number to lookup
  - `grader` string: Grading company (defaults to PSA)
  - `days` integer: Number of days of price history to retrieve (1-365, defaults to 180)

## Response `200`

Successful Response

- CertLookupResponse: Response model for certificate lookup endpoint.
  - `cert_info` GemRateCertInfo, required: Certificate verification information.
    - `grader` string, required: Grading company (e.g., PSA, BGS, CGC)
    - `cert` string, required: Certificate number
    - `grade` string, required: Card grade (e.g., PSA 10, BGS 9.5)
    - `gemrate_id` string, nullable: Unique card identifier
    - `universal_gemrate_id` string, nullable: Universal card identifier
    - `description` string, nullable: Card description from certificate
  - `card` CardDetails: Detailed card information and metadata.
    - `card_id` string, required: Unique card identifier
    - `description` string, nullable: Full card description
    - `player` string, nullable: Player or character name
    - `set` string, nullable: Card set name
    - `number` string, nullable: Card number in set
    - `variant` string, nullable: Card variant (e.g., Base, Refractor, Prizm)
    - `image` string, nullable: Card image URL
    - `category` string, nullable: Card category (e.g., Baseball, Basketball, Pokemon)
    - `category_group` string, nullable: Category group, derived from the catalog category for indexed cards
    - `set_type` string, nullable: Set type, derived from the catalog set name for indexed cards
  - `prices` PriceHistory[]: Daily price history for the card
    - `closing_date` string, required: Date of the price point
    - `Grade` string, required: Card grade
    - `card_id` string, required: Card ID
    - `price` string, required: Price value
  - `card_source` string, nullable: How the card was resolved: 'gemrate_id' for a direct GemRate ID -> CardHedge lookup, or 'card_match' when that lookup found nothing and the card was matched from the GemRate description via the AI card-match fallback. Null when no card was resolved. Cards resolved via 'card_match' have null 'category_group' and 'set_type' -- the matcher does not return those two fields.
  - `match_confidence` number, nullable: AI match confidence (0-1) when 'card_source' is 'card_match'; null otherwise. Treat results derived from a low-confidence match with care.

## Other responses

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

## 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/prices-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)