Historical Shares Outstanding API for Python Research

A historical shares outstanding API should return the share count recorded for a ticker on an as-of date, not today's share count applied to an old price. That distinction is required for studying issuance, repurchases, and historical market capitalization without pushing later capital-structure information backward.

Alphanume serves shares_outstanding through the Historical Market Cap dataset. Each row is keyed by date and ticker and includes both shares_outstanding and market_cap. The pair makes it possible to inspect whether a large change in company value coincided with a change in the share base, while keeping the observation date explicit.

Start with the four-field contract

Shares outstanding is not the same as free float. Restricted or closely held shares can be outstanding without being readily tradeable. The endpoint also does not label every change as issuance, a buyback, a split, a merger, or a vendor revision. Those explanations need separate corporate-action evidence. A jump in the series is a condition to investigate, not a completed event classification.

Query one ticker with an as-of window

Use a bounded range and read the key from an environment variable. The API supports an exact date and the standard date_gte, date_lte, date_gt, and date_lt filters. A ticker or at least one date filter is required.

import os
import pandas as pd
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_gte": "2025-01-01",
        "date_lte": "2025-12-31",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

shares = pd.DataFrame(payload["data"])
shares["date"] = pd.to_datetime(shares["date"])
shares = shares.sort_values("date")

For a single ticker, continue through pagination whenever has_more is true. Pass both values from next_cursor as cursor_date and cursor_ticker. Sending only one cursor component returns an error. Save the raw pages before transforming them so an audit can distinguish source rows from DataFrame logic.

Calculate changes without naming the cause

Month-over-month changes are useful for finding dates that deserve a corporate-action review. Resample only after sorting the observations and decide whether month-end means the last available trading observation or a calendar date. Then calculate both the level change and percentage change.

monthly = (
    shares.set_index("date")
          .resample("ME")
          .last()
          .dropna(subset=["shares_outstanding"])
)

monthly["shares_change"] = monthly["shares_outstanding"].diff()
monthly["shares_change_pct"] = monthly["shares_outstanding"].pct_change()

ax = monthly["shares_outstanding"].plot(
    title="Historical shares outstanding",
    ylabel="Shares",
)
figure = ax.get_figure()

A positive change can be consistent with issuance, equity compensation, acquisition consideration, conversion, or a split adjustment. A negative change can be consistent with repurchases, a reverse split, or another capitalization event. The series alone does not choose among them. Cross-check flagged dates against dated filings and corporate-action records before assigning a cause.

Use market cap as a consistency check

The paired market_cap field provides context. If shares change sharply while market cap is roughly stable, the implied per-share value should move in the opposite direction. If both change, price and share count can contribute simultaneously. Calculate an implied value only as a diagnostic and compare it with a separately sourced adjusted price series rather than assuming the quotient resolves every corporate action.

Historical market cap and shares outstanding are point-in-time inputs, but they do not cure a current-survivor universe, ticker-history gaps, incorrect split adjustments, or missing delisted returns. The Historical Market Cap guide explains coverage and pagination, while the API reference lists the exact request and response fields.

Before comparing issuers, verify that every series uses the same share-count unit and observation rule. A percentage change that crosses a ticker transition or an unreviewed split boundary should remain flagged for investigation rather than entering a cross-sectional rank.

Handle access and missing history honestly

• Coverage can begin on different dates for different tickers, so keep each first-available date.
• A missing observation is not a zero share count and should not be forward-filled across an unbounded gap.
• A ticker change can break entity continuity even when both symbols have valid rows.
• Free access supplies the trailing 20 trading sessions after a one-trading-session delay; Pro supplies current data and full history.
• A long historical issuance claim needs full coverage and separately verified corporate-action evidence.

The existing Historical Market Cap in Python guide covers a broader pull. This workflow is narrower: it treats shares outstanding as the research object and requires every detected change to remain unlabeled until another source explains it.

Save one reproducible change report

Choose one ticker and one year with full access. Save the raw API pages, sorted daily observations, month-end table, change chart, and a review table for every month above a predefined percentage threshold. For each flagged month, record whether a filing or corporate action supports an issuance, repurchase, split, or unresolved classification. Rerun the notebook and confirm the same dates are flagged before scaling to a universe.