---
title: "Get Price History for a Card"
method: POST
path: "/v1/cards/prices-by-card"
tags: ["Pricing & Valuations"]
---

# Get Price History for a Card

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

## Request

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

Get price history for a specific card and grade.

Requires a card_id. If you only have a card name/description, call `card-match` or
`card-search` first to get the card_id, then use it here.

Returns daily price points for the card at the requested grade. By default the
window ends today, so `days` alone reaches back at most one year (366 days).
Results are cached for improved performance.

## Getting price history older than one year

Set `end_date` to shift the `days` window into the past and page backwards,
one window at a time. Each response covers `(end_date - days, end_date]` —
exclusive start, inclusive end — so consecutive pages are contiguous and
never overlap or skip a day.

**Paging by calendar year:**

| Page | Request body |
|------|--------------|
| This year to date | `{"card_id": "...", "grade": "PSA 9", "days": <days since Dec 31>}` |
| 2025 | `{"card_id": "...", "grade": "PSA 9", "days": 365, "end_date": "2025-12-31"}` |
| 2024 (leap year) | `{"card_id": "...", "grade": "PSA 9", "days": 366, "end_date": "2024-12-31"}` |
| 2023 | `{"card_id": "...", "grade": "PSA 9", "days": 365, "end_date": "2023-12-31"}` |
| ... | continue stepping `end_date` back a year at a time |

Stop paging when a response returns an empty `prices` list — you have reached
the start of the card's history (price coverage generally begins around
spring 2020). Use `days: 366` for leap years so the page covers the full
calendar year; `end_date` may not be in the future.

Windows that end in the past are immutable, so they are cached longer
(24 hours) than live windows (1 hour) — historical pages are fast and cheap
to re-request.

**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 '{
       "card_id": "1587446850514x224832321163624450",
       "grade": "PSA 9"
     }' \
     "https://api.cardhedger.com/v1/cards/prices-by-card"

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

# Historical: calendar year 2024 (366 days, leap year)
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{
       "card_id": "1587446850514x224832321163624450",
       "grade": "PSA 9",
       "days": 366,
       "end_date": "2024-12-31"
     }' \
     "https://api.cardhedger.com/v1/cards/prices-by-card"
```

Returns price history (default window: 180 days; max: 366 days per window).

## Request body

- PricesByCardRequest: Request parameters for prices by card endpoint.
  - `card_id` string, required: Unique card identifier
  - `grade` string, required: Grade (e.g., 'PSA 9', 'BGS 9.5')
  - `days` integer: Length of the price window in days (1-366, defaults to 180). 366 is allowed so a single window can cover a full leap year.
  - `end_date` string, date, nullable: Optional end of the price window (YYYY-MM-DD, inclusive). Defaults to today. Set it in the past to retrieve history older than one year by paging windows back in time, e.g. days=365 with end_date=2025-12-31, then days=366 with end_date=2024-12-31 (leap year), and so on. The window covers (end_date - days, end_date].

## Response `200`

Successful Response

- PricesByCardResponse: Response model for prices by card endpoint.
  - `prices` PriceHistory[], required: Daily price history for the specified card and grade
    - `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

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