---
title: "Get Card Details by Certificate Numbers (Batch)"
method: POST
path: "/v1/cards/details-by-certs"
tags: ["Pricing & Valuations"]
---

# Get Card Details by Certificate Numbers (Batch)

`POST /v1/cards/details-by-certs`

## Request

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

Get card details for multiple certificate numbers in a single request.

This endpoint performs batch lookups without price history:
1. Checks the persistent validated-certificate cache for each certificate;
   queries GemRate only for certificates not 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. Returns certificate info and card details (or null if not found in either lookup)

`card_source` reports how each 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 low-confidence matches with care.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "certs": ["76676185", "50000000", "12345678"],
       "grader": "PSA"
     }' \
     "https://api.cardhedger.com/v1/cards/details-by-certs"
```

Returns card details for each certificate. Cards not found in CardHedge will have null card field.
Maximum 100 certificates per request.
Each submitted certificate counts as one unit toward the customer's minute
and day rate limits, including duplicate and cached certificates. A batch
that exceeds the remaining allowance is rejected with HTTP 429 before any
certificates are processed. GemRate HTTP 400 not-found results are cached
by grader and certificate and reused on later requests.

Each account also has a daily budget of **uncached** certificate lookups
(shared by every certificate endpoint and every API key of the account,
resetting at 00:00 UTC). Only certificates that were never looked up before
spend it. Once it is spent, cached certificates are still served and any
other certificate comes back with `error: "gemrate_daily_quota_exceeded"`;
if none of the batch could be served the request returns HTTP 429 with a
`Retry-After` header.

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

- BatchCertLookupRequest: Request parameters for batch certificate lookup endpoint.
  - `certs` string[], required: List of certificate numbers to lookup (max 100); each entry counts toward minute and day rate limits
  - `grader` string: Grading company (defaults to PSA)

## Response `200`

Successful Response

- BatchCertLookupResponse: Response model for batch certificate lookup endpoint.
  - `results` SingleCertResult[], required: List of certificate lookup results
    - `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
    - `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.
    - `error` string, nullable: Set to 'gemrate_daily_quota_exceeded' when this certificate needed an uncached GemRate lookup but the account's daily budget for such lookups was already spent (it resets at 00:00 UTC). The row then carries placeholder cert_info (grade 'Unknown') and no card; retry after the reset. Null for every other row.
  - `total_requested` integer, required: Total number of certificates requested
  - `total_found` integer, required: Number of cards found in database with pricing data

## 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`: 2 info
  - added the non-success response with the status `429`
  - added the optional property `results/items/error` to the response with the `200` status

[Operation history](https://skmtc.dev/cardhedger/apis/card-hedge-api/changes/v1/cards/details-by-certs/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)