Get historical shares outstanding
Look up the number of common shares a company reported outstanding on a specific date or over time.
How it works
-
Compare dated counts. Each row gives the number of shares outstanding on its
as_ofdate, newest first. Uselimit=1for the latest observation. Counts can change through issuance, buybacks or splits. -
Choose the date. Use
fromandtofor observation dates. Setknown_byto restrict the history to disclosures available by that day. Useavailable_onfor an exact evidence availability date, oravailable_on_gteandavailable_on_ltefor an inclusive availability window. Availability filters require a known date. Setinclude_sources=truefor the filing date and available source references. -
Find a disclosure by publication date. Use
filing_datefor one date orfiling_date_gteandfiling_date_ltefor an inclusive range. These filters require the filing or notice to have a known publication date. -
Check the scope. Counts can come from financial statements and regulatory share-capital notices. A closing count can be calculated when the filing gives both issued and treasury shares for that date. A stock or fund identifier can resolve successfully and still have no share-count history. Counts are reported in shares with no split adjustment. When a filing identifies a share class, its taxonomy member appears in
dimensions. A class row counts only that class. For weighted-average shares used in EPS, useget_financials. An empty list means no supported observation matched. A null count means the exact number could not be established.
Request
GET /api/v1/shares-outstanding with your API key. AI assistants call it as the get_shares_outstanding tool, with the same parameters.
Parameters
qstringrequired
Ticker with its exchange code or MIC (AAPL:US, AAPL:XNAS, TSCO:XLON), ISIN, CUSIP, SEDOL, WKN, FIGI, LEI, CIK or company registration number. Any ticker and mic a listing returns work as ticker:mic.
More parameters
include_sourcesboolean
Include available source documents and supporting evidence. Omit for data only.
Default: false
fromdate
Earliest observation date, inclusive.
YYYY-MM-DD
todate
Latest observation date, inclusive.
YYYY-MM-DD
known_bydate
Only include disclosures known by this date.
YYYY-MM-DD
filing_datedate
Published on this date.
YYYY-MM-DD
filing_date_gtedate
Published on or after this date.
YYYY-MM-DD
filing_date_gtdate
Published after this date.
YYYY-MM-DD
filing_date_ltedate
Published on or before this date.
YYYY-MM-DD
filing_date_ltdate
Published before this date.
YYYY-MM-DD
available_ondate
Evidence available on this date.
YYYY-MM-DD
available_on_gtedate
Evidence available on or after this date.
YYYY-MM-DD
available_on_gtdate
Evidence available after this date.
YYYY-MM-DD
available_on_ltedate
Evidence available on or before this date.
YYYY-MM-DD
available_on_ltdate
Evidence available before this date.
YYYY-MM-DD
limitinteger
Maximum number of observations.
Default: 20 · From 1 to 100
offsetinteger
Number of observations to skip.
Default: 0 · From 0 to 9007199254740991
Response
JSON with these fields. A field the source doesn't report is null or left out.
queryRequested identifier
next_offsetOffset of the next page, or null
shares_outstandingarray of objectsrequired
Show child attributes
as_ofShare-count observation date
available_onDate the evidence supporting this count was available
outstanding_sharesReported common shares outstanding, or null when unresolved
dimensionsarray of objects
Show child attributes
memberobject
Show child attributes
nameReported share-class member
namespaceTaxonomy that defines the member
sourcesarray of objects
Show child attributes
source_urlPublic filing, report package or regulatory notice URL
fact_idIdentifier of the supporting fact or note when available
pointerJSON pointer in the filing data when available
filing_dateWith include_sources=true, the filing or regulatory notice publication date when known
matchIdentifier lookup outcome. A found match can still have an empty page.
Errors
| Status | Meaning |
|---|---|
| 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up |
| 401 | Missing, unknown or revoked API key |
| 402 | No active plan or trial, or the included request allowance is used |
| 403 | API access of the account is suspended |
| 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome |
| 429 | Over the plan's rate limit; Retry-After says when to retry |
| 500 | Internal error; the same request is unlikely to succeed on retry |
| 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known |
Errors are JSON with an error message saying what to fix. Errors are free. See Errors and limits.