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

# Get Player Index

`POST /v1/cards/player-index`

## Request

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

Latest cached player index: a market-cap-weighted average price (USD) of
the player's top-10 cards, with 1d/7d/30d/90d/365d changes and the cards
behind it.

Identify the player by `player_id` (recommended — from `player-search`) or
by `name` (+ optional `category`). A name must match exactly one player,
otherwise the response is 409 with `candidates`. Merged duplicate IDs
resolve to their canonical player (`resolution.resolved_via: "alias"`).

`status` is `current` (updated within `PLAYER_INDEX_STALE_DAYS` days,
default 2), `stale` (older; still served — the API never triggers a
recalculation), or `withheld` (at least `PLAYER_INDEX_WITHHOLD_FOREIGN_PCT`
percent, default 25, of the index's weight comes from other players'
cards; `value` is null and `integrity.reason` explains).

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

## Request body

- PlayerIndexRequest
  - `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.
  - `include_constituents` boolean: Include the cards behind the index

## Response `200`

Successful Response

- PlayerIndexResponse
  - `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
  - `index` IndexSnapshot, required
    - `value` number, nullable, required: USD: market-cap-weighted average price of the top-10 cards; null when withheld
    - `as_of` string, date, required
    - `status` 'current' | 'stale' | 'withheld', required
    - `days_since_update` integer, required
    - `volume_30d` integer, nullable
    - `card_count` integer, nullable
    - `changes` object, required
    - `methodology` Methodology, required
      - `algorithm` string, nullable
      - `base_grade` string, nullable
      - `version` string, nullable
  - `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
  - `constituents` ConstituentBlock[]
    - `card_id` string, required
    - `card_name` string, nullable
    - `set` string, nullable
    - `variant` string, nullable
    - `grade` string, nullable
    - `price` number, nullable
    - `weight` number, required: Share of the index (weights sum to 100)
    - `volume_30d` integer, nullable
    - `owned_by_player` boolean, nullable: False when the card belongs to another player; null when unknown

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