# 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 {#how-it-works} - **Compare dated counts.** Each row gives the number of shares outstanding on its `as_of` date, newest first. Use `limit=1` for the latest observation. Counts can change through issuance, buybacks or splits. - **Choose the date.** Use `from` and `to` for observation dates. Set `known_by` to restrict the history to disclosures available by that day. Use `available_on` for an exact evidence availability date, or `available_on_gte` and `available_on_lte` for an inclusive availability window. Availability filters require a known date. Set `include_sources=true` for the filing date and available source references. - **Find a disclosure by publication date.** Use `filing_date` for one date or `filing_date_gte` and `filing_date_lte` for 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, use `get_financials`. An empty list means no supported observation matched. A null count means the exact number could not be established. ## Request {#request} `GET /api/v1/shares-outstanding` with your API key. AI assistants call it as the `get_shares_outstanding` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/shares-outstanding?q=AAPL:US" \ -H "Authorization: Bearer $FDB_API_KEY" ``` ## Parameters {#parameters} | Parameter | Type | Description | |---|---|---| | `include_sources` | boolean | Include available source documents and supporting evidence. Omit for data only. Default: `false`. | | `q` (required) | string | 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. | | `from` | date | Earliest observation date, inclusive. | | `to` | date | Latest observation date, inclusive. | | `known_by` | date | Only include disclosures known by this date. | | `filing_date` | date | Published on this date. | | `filing_date_gte` | date | Published on or after this date. | | `filing_date_gt` | date | Published after this date. | | `filing_date_lte` | date | Published on or before this date. | | `filing_date_lt` | date | Published before this date. | | `available_on` | date | Evidence available on this date. | | `available_on_gte` | date | Evidence available on or after this date. | | `available_on_gt` | date | Evidence available after this date. | | `available_on_lte` | date | Evidence available on or before this date. | | `available_on_lt` | date | Evidence available before this date. | | `limit` | integer: 1–100 | Maximum number of observations. Default: `20`. | | `offset` | integer: 0–9007199254740991 | Number of observations to skip. Default: `0`. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. | Field | Description | |---|---| | `query` | Requested identifier | | `next_offset` | Offset of the next page, or null | | `shares_outstanding[].as_of` | Share-count observation date | | `shares_outstanding[].available_on` | Date the evidence supporting this count was available | | `shares_outstanding[].outstanding_shares` | Reported common shares outstanding, or null when unresolved | | `shares_outstanding[].dimensions[].member.name` | Reported share-class member | | `shares_outstanding[].dimensions[].member.namespace` | Taxonomy that defines the member | | `shares_outstanding[].sources[].source_url` | Public filing, report package or regulatory notice URL | | `shares_outstanding[].sources[].fact_id` | Identifier of the supporting fact or note when available | | `shares_outstanding[].sources[].pointer` | JSON pointer in the filing data when available | | `shares_outstanding[].filing_date` | With include_sources=true, the filing or regulatory notice publication date when known | | `match` | Identifier lookup outcome. A found match can still have an empty page. | ## Errors {#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](https://financialdb.ai/documentation/api/errors-and-limits.md).