---
title: "Get Card Variants"
method: POST
path: "/v1/cards/card-variants"
tags: ["Card Details"]
---

# Get Card Variants

`POST /v1/cards/card-variants`

## Request

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

Return the other variants (parallels) of a card.

A variant group is every active card sharing the source card's exact `set`,
`number`, and `subset`. Blank, null, `"null"`, and `"none"` subsets are
treated as `"Base Set"` when comparing identity. The source card itself is
excluded. Results are ordered by 30-day sales volume descending, with
7-day sales volume and primary price as tie-breakers. At most 100 cards are
scanned as a safety backstop.

Cards without both a set and card number, unknown card IDs, and cards with
no other active variants return an empty list.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here"          -H "Content-Type: application/json"          -d '{"card_id":"1587446850514x224832321163624450"}'          "https://api.cardhedger.com/v1/cards/card-variants"
```

## Request body

- CardVariantsRequest: Request parameters for finding the other variants of a card.
  - `card_id` string, required: Unique Card Hedge card identifier
  - `raw_images_only` boolean, nullable: Image preference. Omitted (default): return the raw card photo, falling back to the graded slab image only when no raw photo exists. true: force raw-only (no graded fallback). false: prefer the graded slab image.

## Response `200`

Successful Response

- CardVariantsResponse: Other active cards sharing the source card's set, number, and subset.
  - `count` integer, required: Number of other variants returned
  - `cards` CardSearchCard[]: Other active variants, ordered by 30-day sales volume, then 7-day sales volume, then primary price
    - `description` string, required: Full card description
    - `player` string, required: Player or character name
    - `set` string, required: Card set name
    - `number` string, required: Card number in set
    - `variant` string, required: Card variant (e.g., 'Base', 'Reverse Foil')
    - `card_id` string, required: Unique card identifier
    - `image` string, required: Card image URL
    - `category` string, required: Card category
    - `category_group` string, required: Category group
    - `set_type` string, required: Set type
    - `7 Day Sales` integer, required: Sales in last 7 days
    - `30 Day Sales` integer, required: Sales in last 30 days
    - `rookie` boolean, required: Whether the card is a rookie card
    - `gain` number, required: Price gain percentage
    - `prices` CardPrice[], required: Price information at different grades
      - `grade` string, required: Card grade (e.g., 'Raw', 'PSA 10')
      - `price` string, required: Price in string format
    - `subset` string, nullable: Card subset within the set (e.g. 'Base Set', 'Chrome'); null when the card has no subset

## Other responses

- `422`: Validation Error

---

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