stocks_get_financial_metrics
Derived financial metrics for one US public company — computed here so you never have to do the arithmetic yourself.
Public-key response
Price-derived valuation metrics (market cap, P/E, P/S, P/B, EV/EBITDA, FCF yield) are omitted for public keys; the response flags the omission via meta.restricted_omitted.
Description
Derived financial metrics for one US public company — computed here so you never have to do the arithmetic yourself.
Prefer this tool over pulling raw statements and dividing: the numbers
are served with their definitions, so an analysis stays accurate and
auditable. The result is the shared envelope. data.metrics is a
bounded, newest-first list of per-period fundamentals; each period keys a
metrics object with:
- margins:
gross_margin,operating_margin,net_margin,fcf_margin - growth:
revenue_growth_yoy/_cagr_3y,net_income_growth_yoy/_cagr_3y,fcf_growth_yoy/_cagr_3y - returns (annual only):
roe,roa,roic - leverage/liquidity:
debt_to_equity,net_debt_to_ebitda,current_ratio
data.valuation (may be null if we hold no price) carries current-price
multiples as-of the latest close: market_cap, pe_ttm, ps_ttm, pb,
ev_ebitda, fcf_yield. market_cap is USD price × share count.
Valuation multiples that would mix the USD price with non-USD statement
inputs are omitted with null_reason beginning currency_mismatch;
fundamentals-only ratios computed within statement currency are
unaffected.
Every metric is a MetricValue: value (exact decimal string, or null
when an input is missing — a bank has no current_ratio, a firm with no
positive pretax income has no roic), unit (ratio = a fraction where
0.46 means 46%; x = a multiple; USD), formula and formula_id, the
exact inputs used, source, and null_reason when null. Ratios are
fractions, not percentages.
Valuation values are derived from provider-licensed price data and are
flagged non_redistributable: true (also on meta); fundamentals are
SEC-derived and redistributable.
On the public surface, the valuation block is omitted and its source is
listed in meta.restricted_omitted; fundamental metrics remain available.
The default is 4 fiscal periods and the maximum is 12. To continue,
pass pagination.next_cursor back as cursor; stop when
pagination.has_more is false. Example:
stocks_get_financial_metrics(ticker="AAPL", period="annual", limit=4).
Errors carry a machine code: unknown_entity for a well-formed symbol
we hold no mapping for, bad_parameter for input the schema can't reject.
Parameters
Input schema advertised to MCP clients and mirrored by the REST query string.
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| ticker | string | Yes | — | — | Ticker symbol, e.g. 'AAPL' or 'BRK.B' (class separators accepted). |
| period | "annual" | "quarterly" | "ttm" | No | "annual" | — | Fiscal frame the per-period metrics are computed over: 'annual' (FY), 'quarterly' (Q1-Q4), or 'ttm' (trailing twelve months, where populated). Returns metrics (returns like ROE/ROA/ROIC are annual-only) are null for non-annual frames with a reason. |
| limit | integer | No | 4 | min 1, max 12 | Fiscal periods to return, newest first (1-12). |
| cursor | string | null | No | null | — | Opaque pagination cursor from a previous response's `pagination.next_cursor`; omit to start from the newest period. |
Provenance
Sources behind every value this tool returns.
- sec_edgar_companyfactsU.S. Securities and Exchange Commission (EDGAR)
tiingoProvider-licensed source; not served to public keys
Dataset registry: stocks_daily_prices, stocks_fundamentals