Insights
How to Get a Stock's Historical Market Cap by Date
Alphanume Team · July 29, 2026
To get a stock's historical market cap by date, query a stored point-in-time record for the ticker and trading date. Avoid rebuilding the value from an old price and today's shares outstanding.
Alphanume Historical Market Cap returns date, ticker, market_cap, and shares_outstanding as observed on each covered trading date. For the concrete request "AAPL as known on June 28, 2024," call GET /v1/historical-market-cap with ticker=AAPL and date=2024-06-28.
That stored pair matters because market capitalization equals price times shares outstanding, and both inputs change. Applying today's share count to a 2024 price can incorporate later issuance, repurchases, conversions, or acquisitions. The result is a historical-looking number that nobody could have observed on the requested date.
Use the exact-date contract
Parameter or field | Role | Rule |
|---|---|---|
ticker | Select one equity symbol | Case-insensitive exact match |
date | Select one observation date | YYYY-MM-DD and no range filters in the same request |
market_cap | Capitalization on that date | Keep as the stored as-of value |
shares_outstanding | Share count on that date | Company-level count, not free float |
count | Rows in the response page | Expect zero or one for one ticker and one date |
The endpoint requires a ticker or at least one date filter. An exact date without a ticker returns the covered market-wide cross-section for that day. A ticker plus exact date narrows the job to the single record you actually asked for and avoids unnecessary pagination.
Exact date cannot be combined with date_gte, date_lte, date_gt, or date_lt. Invalid combinations return a 400 response, so treat that as a query error rather than an empty result.
Request AAPL on June 28, 2024
import os
import requests
response = requests.get(
"https://api.alphanume.com/v1/historical-market-cap",
headers={"X-API-Key": os.environ["ALPHANUME_API_KEY"]},
params={"ticker": "AAPL", "date": "2024-06-28"},
timeout=30,
)
response.raise_for_status()
payload = response.json()
assert payload["count"] in {0, 1}
if payload["count"] == 1:
row = payload["data"][0]
assert row["ticker"] == "AAPL"
assert row["date"] == "2024-06-28"Keep a zero-row result explicit. It can mean the requested date is not a trading session, the symbol has no coverage on that date, or the identifier assumption is wrong. It does not mean the company had zero market capitalization. The companion coverage endpoint lists each available ticker and its first covered date, which helps separate early-history gaps from a typo.
Free access exposes a trailing 20-trading-session window delayed by one session. A 2024 request needs historical access. A 403 DATE_RANGE_RESTRICTED response is an access result and should never be stored as count zero.
Store the request parameters with the response because a one-row JSON file is otherwise easy to mislabel later. Include the endpoint path, normalized ticker, requested calendar date, access tier, HTTP status, returned count, and retrieval time. If the response date differs after any calendar fallback, keep both dates as separate columns rather than renaming the returned observation.
Verify the returned identity and date
Check | Pass condition | Failure action |
|---|---|---|
Date | Returned date equals requested date | Stop instead of substituting a nearby day |
Ticker | Returned ticker equals normalized symbol | Review ticker changes or reuse |
Market cap | Finite positive value for the intended analysis | Preserve null or invalid row in coverage audit |
Share count | As-of count retained with market cap | Do not replace with a current quote source |
Tier | Requested date is visible | Change access or test a permitted date |
If the research job permits the last trading day before a weekend or holiday, implement that calendar rule outside the exact-date call and record the substituted date. Silently accepting a nearby observation changes the question from "on this date" to "around this date."
For a market-wide date, large responses use keyset pagination ordered by date and ticker. The single-ticker exact-date job should remain one row, so an unexpected cursor or duplicate row is a reason to stop and inspect the query instead of taking the first record.
Know what the row cannot fix
- A ticker alone does not guarantee company identity through mergers, reorganizations, and symbol reuse.
- Historical market cap does not provide a standalone price series or repair split adjustments in another source.
- Shares outstanding includes restricted and insider holdings and therefore differs from free float.
- A stored company value does not make a current-survivor universe historically complete.
- Coverage begins on different dates across tickers, so missing early rows need their own report.
Market-cap data solves the as-of capitalization input. Identifier history, universe membership, corporate actions, prices, delisting outcomes, and execution remain separate contracts.
Save the one-row audit
Run the AAPL request, save the untouched JSON response, and write an audit row containing requested date, returned date, ticker, market cap, shares outstanding, access tier, status code, and retrieval timestamp. Then repeat the same query once and compare the normalized result before using it in a larger backtest.
Inspect coverage and fields on the Historical Market Cap page, then use the Historical Market Cap guide when the single-date lookup expands into paginated histories or market-wide cohorts.