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

# Get Category Index History

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

## Request

- Base URL: `https://api.cardhedger.com`
- URL: `https://api.cardhedger.com/v1/cards/category-index-history`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/cardhedger/apis/card-hedge-api/docs/v1/cards/category-index-history/post.ts> (a function with typed inputs; its response is checked against the schema)

A category index's values over a period of time.

Identify the index by `slug` (from `category-index-search`) or name.
The window defaults to the 365 days up to the latest index date; send a
`start_date` on or before the index's `base_date` for its whole history.
`weekly` points are averages keyed by the Monday, `monthly` by the 1st.

`summary` gives the period's start and end values, change, high and low,
always from the daily values.

Don't know the slug? List every index with `category-index-search`
(send `{}`), or pass the index's name instead, e.g. `"Pokemon"`. An
unknown index is a 404 whose `detail.available` lists every valid slug.

**Example curl:**
```bash
curl -X POST -H "X-API-Key: your-api-key-here" \
     -H "Content-Type: application/json" \
     -d '{"index":"baseball","start_date":"2026-10-31","end_date":"2026-11-06"}' \
     "https://api.cardhedger.com/v1/cards/category-index-history"
```

## Request body

- CategoryIndexHistoryRequest
  - `index` string, required: Index `slug` (from category-index-search, e.g. `baseball`) or name, case-insensitive.
  - `start_date` string, date, nullable: First day (YYYY-MM-DD). Default: end_date minus 365 days. A date before the index's `base_date` returns its whole history.
  - `end_date` string, date, nullable: Last day (YYYY-MM-DD). Default: the latest index date.
  - `interval` 'daily' | 'weekly' | 'monthly': daily | weekly (Monday-keyed averages) | monthly (1st-of-month averages)

## Response `200`

Successful Response

- CategoryIndexHistoryResponse
  - `index` CategoryIndexInfo, required
    - `slug` string, required: Stable key; pass it to category-index-history
    - `name` string, required
    - `category` string, nullable
    - `description` string, nullable
    - `image_url` string, nullable
    - `base_date` string, date, nullable: First day of the index's history
  - `interval` 'daily' | 'weekly' | 'monthly', required
  - `start_date` string, date, required
  - `end_date` string, date, required
  - `summary` CategoryIndexPeriodSummary, required: The period's numbers, from the daily values whatever the interval.
    - `start_value` number, nullable
    - `end_value` number, nullable
    - `change` CategoryIndexChange
      - `abs` number, required: Change in index points
      - `pct` number, required: Percent change
    - `high` number, nullable
    - `high_date` string, date, nullable
    - `low` number, nullable
    - `low_date` string, date, nullable
  - `points` CategoryIndexPoint[], required
    - `date` string, date, required
    - `value` number, nullable, required: Index level (daily) or the bucket's average

## Other responses

- `404`: `index_not_found`: no published index has that slug or name; `available` lists the slugs
- `409`: `ambiguous_index`: the name is shared by several indexes; `candidates` lists their slugs
- `422`: `invalid_request`: a malformed body, or start_date after end_date
- `502`: `upstream_error`: index data is temporarily unavailable

## Changes

- **2026-11-07** `f7ab0cecf985`: 1 info
  - endpoint added

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