Fundamentals API
Standardized income, balance, cash-flow, and ratio values for a company — annual, quarter, and TTM for the periods we have on that listing.
Fundamentals is the standardized numbers we store for a company: income-statement lines, balance-sheet lines, cash-flow lines, and calculated ratios (current ratio, ROE, P/E, …). These are not the filer's raw XBRL tags — those are XBRL. Full nested statements (the layout you would put in a table) live one level down in Financials Standardized.
Resolve the company (Entities). If you do not already have metric ids, get them from Fundamentals Metrics. Then call Fundamentals with id and those ids.
You can search these ids on Coverage — Fundamentals metrics. That table is a snapshot and can be behind the API. For the current list, call Fundamentals Metrics.
This catalog is not the screener field list. Screener Metrics ids are perioded snapshot columns (ttmRevenue_usd, marketCap_usd). Fundamentals Metrics ids are the underlying datapoints (revenue, currentRatio, PE) with periodicity as a parameter.
Coverage
- Who. Companies (and fund lines) that have statement rows in our warehouse for the listing you resolve. A valid listing with no statements returns an empty
dataarray, not an error. - Which numbers. Standardized lines and ratios — the same formulas the site uses. Not as-reported tag names (
us-gaap:…). - Which periods.
fy(fiscal year),quarter, andttm(trailing twelve months). We do not store SEMI, YTD, or restatement flavors. Point-in-time as-of is not on these endpoints (pit_data_itemson Metrics is reserved; the current catalog is all non-PIT). - How far back. All fiscal periods we have for that listing, capped at 100 (or 252 points when
daily). Omitlimitto take that full available history. Optionalperiod_start/period_end(YYYY-MM-DD) cut on period-end date. Do not assume a fixed “30 years” for every name. - Currency. Default is reporting currency. Pass an ISO code to convert money metrics at latest warehouse spot (not a period-end historical rate). See Currency.
id on value tools is the same handle as Entity Reference. See Ids you can send. Unresolved ids are 404.
Explore coverage
See what's in scope for this API group—datasets, date ranges, and counts—in the coverage overview.
What to call
| You have | Call |
|---|---|
| You need the id, category, or formula for a metric | Fundamentals Metrics |
| A ticker or CIK and a list of metric ids | Fundamentals |
| A full income, balance, or cash-flow table | Income Statement, Balance Sheet, Cash Flow Statement |
| The + / - nesting for those tables | Financials Metrics |
| Tagged SEC facts for the cited filing | XBRL |
| A screen on current ratios | Screener |
| A ticker or CIK for one issuer | Entity Reference |
Periods
One metric id covers the periods listed in periodicities (fy, quarter, ttm, daily). You do not get a separate id per period.
On Fundamentals, periodicity is a list (comma-separated on GET). Default is fy. You may combine fy, quarter, and ttm in one response — each observation is tagged. daily cannot mix with fiscal periods.
On statement endpoints, periodicity is a single value so the table stays one grid. include_ltm=true on annual requests appends a Last-12M column when it is not the same as the latest FY.
Optional period_start / period_end (YYYY-MM-DD) filter on period-end date. Optional limit keeps the latest N matching periods. Omit limit for all available history (capped at 100 fiscal periods or 252 daily points).
We do not store SEMI, YTD, or restatement flavors. Point-in-time as-of is not on these endpoints. pit_data_items on Fundamentals Metrics is reserved; the current catalog is all non-PIT.
Currency
Omit currency to keep reporting currency (the statement reportedCurrency). Pass an ISO code (USD, EUR, CAD) to convert money metrics only (is_currency=true). Ratios, percents, and share counts are left alone. Codes are the same as Forex.
Conversion uses the latest warehouse forex quotes, crossed via USD. It is latest spot, not a period-end historical rate — we do not have a dated FX book. Price-bound market metrics convert from listing / trading currency; statement money converts from reporting currency. The currency object on the response has both legs when they applied. Forex Convert is the same rate path.
Latest spot
currency= is the current warehouse quote, not a period-end historical FX rate. Same book as Forex.
Growth
growth=none (default) returns values only. growth=period is adjacent percent change (same formula as Financials %Chg on the site). growth=yoy is the same fiscal period in the prior year. Growth is computed from the series in the response, not from a separate growth table.
Categories
Every metric has a category and a subcategory. Both are required. Filters on Fundamentals Metrics are optional and use the same names as the groups that currently have metrics — those lists also come back on the response as categories and subcategories.
| Category | What it holds | Subcategories with metrics |
|---|---|---|
INCOME_STATEMENT | Income-statement lines | INCOME_STATEMENT, NON-OPERATING, PER_SHARE, SUPPLEMENTAL, EXPENSES, OPERATING_COST, NON-RECURRING_ITEMS, REVENUES, NET_INCOME |
BALANCE_SHEET | Balance-sheet lines | ASSETS, BALANCE_SHEET, LIABILITIES, SHAREHOLDERS_EQUITY |
CASH_FLOW | Cash-flow lines | CHANGE_IN_CASH, FINANCING_ACTIVITIES, OPERATING_ACTIVITIES, INVESTING_ACTIVITIES, SUPPLEMENTAL |
RATIOS | Calculated ratios | FINANCIAL, GROWTH_RATE, LIQUIDITY, PROFITABILITY, SIZE, VALUATION |
MARKET_DATA | Shares outstanding, market cap | MARKET_DATA |
MISCELLANEOUS | Scores and indicators | INDICATOR |
subcategory can be sent without category. A pair that does not belong together (for example INCOME_STATEMENT + ASSETS) returns an empty metrics array, not an error. Unknown enum values are a 400.
Metric ids
Ids are stable strings. They are not display labels.
| Kind | Examples |
|---|---|
| Statement line | revenue, totalAssets, freeCashFlow |
| Warehouse ratio | currentRatio, returnOnEquity, PE |
| Composed ratio | dupontRoe3 |
When a row is an alias of another metric, base_code is the canonical id. Use either id; value tools resolve aliases.
Cash-flow statement net income is cashflowNetIncome so it does not collide with income-statement netIncome.
On Fundamentals, each observation’s values map is keyed by those ids (the keys keep catalog spelling, not snake_case).
Data type and PIT
data_type is float, integer, or string. value_type is the semantic type (money, ratio, percent, per_share, shares, integer, score).
is_pit / is_non_pit say whether the metric exists in a point-in-time dataset, a period-end dataset, or both. pit_data_items=true returns only PIT metrics. The current catalog is all non-PIT: a true PIT filter is a valid empty list.
factor is the scale on the stored number. 1 means as stored, not scaled to millions.
How the catalog is built
Rows come from the same formulas and statement layout the site uses — not a live third-party metrics feed.
- Stored ratios are pre-calculated (current ratio, ROE, P/E).
- Statement lines are the standardized income, balance, and cash-flow rows.
- Composed ratios are calculated after fetch (for example a three-point DuPont ROE) and are not stored as their own column.
Metrics catalog calls return that combined list. Value tools fetch the series for the company you pass.
Request shape
Fundamentals Metrics is GET /v2/fundamentals/metrics. All query parameters are optional.
Fundamentals is GET /v2/fundamentals. Required: id, metrics (comma-separated on GET, maximum 80). Arrays are comma-separated, not repeated keys.
Response shape
Fundamentals Metrics is { category, subcategory, metric_data_type, pit_data_items, count, categories, subcategories, metrics }.
Fundamentals is { id, entity, periodicity, currency, metrics, count, data }. data is one object per period with a values map. An empty data array is a valid miss when the listing exists but has no rows in range, not an error.