---
title: "Get Player Index History"
method: POST
path: "/v1/cards/player-index-history"
tags: ["Market Data"]
---

# Get Player Index History

`POST /v1/cards/player-index-history`

## Request

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

Player index values over a date range (default: the 365 days up to the
latest index date; at most 1,830 days).

`weekly` points are averages keyed by the ISO-week Monday, `monthly` by
the 1st. Points built from a constituent set that fails the integrity
check come back with `value: null, withheld: true`.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here"          -H "Content-Type: application/json"          -d '{"name":"Luka Doncic","interval":"monthly"}'          "https://api.cardhedger.com/v1/cards/player-index-history"
```

## Request body

- PlayerIndexHistoryRequest
  - `player_id` string, nullable: Card Hedge player ID (from player-search). Alias IDs resolve to their canonical player.
  - `name` string, nullable: Player name; resolves only when it matches exactly one player (else 409 with candidates).
  - `category` string, nullable: With `name` only: one category (name or slug) to tell same-named players apart.
  - `start_date` string, date, nullable: Default: end_date minus 365 days
  - `end_date` string, date, nullable: Default: the latest index date
  - `interval` 'daily' | 'weekly' | 'monthly': daily | weekly (Monday buckets) | monthly (1st-of-month buckets)

## Response `200`

Successful Response

- PlayerIndexHistoryResponse
  - `player` PlayerBlock, required
    - `player_id` string, required: Canonical Card Hedge player ID
    - `name` string, required
    - `categories` string[]
    - `aliases` string[]: Player IDs merged into this player
  - `resolution` ResolutionBlock, required
    - `requested_player_id` string, nullable
    - `requested_name` string, nullable
    - `requested_category` string, nullable
    - `resolved_via` 'player_id' | 'alias' | 'name', required
  - `interval` 'daily' | 'weekly' | 'monthly', required
  - `start_date` string, date, required
  - `end_date` string, date, required
  - `points` HistoryPointBlock[], required
    - `date` string, date, required
    - `value` number, nullable
    - `volume_30d` integer, nullable
    - `card_count` integer, nullable
    - `withheld` boolean
  - `integrity` IntegrityBlock, required
    - `verdict` 'ok' | 'warning' | 'withheld', required
    - `foreign_weight_pct` number, required: % of index weight from other players' cards
    - `unknown_weight_pct` number: % of index weight whose card owner is unknown
    - `reason` string, nullable

## Other responses

- `404`: `player_not_found` (with `suggestions`) or `index_not_found`
- `409`: `ambiguous_player`: the name matches several players; `candidates` lists them
- `422`: `invalid_request`: both/neither of player_id and name, category without name, unknown category, or a bad window
- `502`: `upstream_error`
- `503`: `identity_unavailable`: the player catalog has not loaded yet; retry shortly

## Changes

- **2026-10-02** `ab9bd6d3c2a9`: 1 info
  - endpoint added

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