---
title: "Point-in-time historical market capitalization: daily market_cap and"
method: GET
path: "/v1/historical-market-cap"
---

# Point-in-time historical market capitalization: daily market_cap and

`GET /v1/historical-market-cap`

## Request

- Base URL: `https://api.alphanume.com`
- URL: `https://api.alphanume.com/v1/historical-market-cap`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Point-in-time historical market capitalization: daily market_cap and
shares_outstanding per US ticker, as they were known on each date (no restatement,
no survivorship bias). The backbone reference for size filters, cap-weighted
baskets, and normalizing anything by company size in a backtest.

Requirements: provide `ticker` OR at least one date filter. A single `date` with no
ticker returns the whole market for that day; a date RANGE without a ticker is
capped at 7 calendar days. Pagination: results are capped at 50,000 rows
per request; when the response has has_more=true, pass next_cursor's date and
ticker back as cursor_date and cursor_ticker to fetch the next page.

Companion tool: list_market_cap_tickers shows which tickers exist and their first
available date.

Requires an Alphanume Pro API key. A 403 PRO_SUBSCRIPTION_REQUIRED or
DATE_RANGE_RESTRICTED error means the key's plan does not cover the request --
it does not mean the data is missing.

## Query parameters

- `ticker` string
- `date` string
- `date_gte` string
- `date_lte` string
- `date_gt` string
- `date_lt` string
- `cursor_date` string
- `cursor_ticker` string

## Response `200`

Matching rows.

- PaginatedEnvelope
  - `count` integer, required
  - `data` object[], required
  - `has_more` boolean, required
  - `next_cursor` object, nullable, required: Keyset cursor: pass its fields back as the cursor_* query parameters to fetch the next page.

## Other responses

- `400`: Invalid or conflicting query parameters.
- `401`: Missing or unrecognized API key.
- `403`: PRO_SUBSCRIPTION_REQUIRED: the key's plan does not include API access; every endpoint requires an active Pro subscription. DATE_RANGE_RESTRICTED: a legacy free-tier key asked for dates outside its window. In both cases the data is not missing.
- `429`: Rate limit exceeded (600/min); the body carries retry_after_seconds.

---

[API](https://skmtc.dev/alphanume/apis/alphanume-api.md) · [All operations](https://skmtc.dev/alphanume/apis/alphanume-api/llms.txt) · [OpenAPI document](https://skmtc.dev/alphanume/apis/alphanume-api/revisions/2cb83f10bba4?raw)