Metric History
get_metric_historyUse this when the user asks for one metric in a given period or over time (gross margin, ROE, P/E and 250+ more): its Q, FY or TTM series; get_financials returns whole statements, and compare_companies sets a company beside its peers. Returns newest-first rows labeled with the company's fiscal_year + fiscal_period — answer a period-specific question ("Q2 FY2025?") from those labels. The period_end calendar date is NOT the fiscal label, especially for non-December FYE companies (AAPL FY ends Sep; CRM FY ends Jan; ORCL FY ends May).
Each row with an SEC accession is cited back to the source filing via the MetricDuck viewer (under vantage_date, the vantage-era filing).
⚠ CONSOLIDATED ONLY — there is no segment/geography/product breakdown here, and no parameter adds one: the metrics layer sums those axes away, so per-member values are never stored. For a BY-SEGMENT series use get_xbrl_facts(ticker, search="<segment name> revenue", period_history=true) (as-filed dimensional facts) or get_filing_section(ticker, "table_segment_reporting") (the schedule, 3 fiscal years per 10-K).
Use Cases:
"What was AAPL's Q2 FY2025 gross margin?" -> get_metric_history("AAPL", "gross_margin")
"ROE last 5 years for MSFT" -> get_metric_history("MSFT", "roe", period_type="FY", window=5)
"As of a past date / point-in-time" -> get_metric_history("MSFT", "revenues", vantage_date="2024-04-30")
Issuer operating KPIs (subscribers, backlog, NIM, occupancy…) are not served here: read them in the company's release, get_filing_section(ticker, "earnings_press_release").
Price-derived multiples here (pe_ratio, ev_ebitda, pb_ratio…) use the PERIOD-END close; for a price on a SPECIFIC date use get_stock_price.
Latest fiscal year during earnings season: full-year results post in an earnings 8-K weeks before the 10-K that populates this FY series, so inside that gap the series ends a year early and this tool appends a pointer to the 8-K (get_filing_section "earnings_income_statement") — the year is not unavailable.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ticker | Yes | Company ticker symbol (e.g., 'AAPL'). Must be exact. | |
| window | No | Max observations returned, newest first. Default 20, max 40. | |
| metric_id | Yes | Exact metric id (lowercase + underscores). Common XBRL financials: gross_margin, oper_margin, net_margin, ebitda_margin, roe, roa, roic, pe_ratio, ev_ebitda, ev_sales, fcf_yield, pb_ratio, current_ratio, debt_to_equity, interest_coverage, revenues, net_income, ebitda, fcf, net_cf_ops, capex, dividends_per_share, dividends_paid, dividend_yield, dividend_payout_ratio, fcf_payout_ratio, dividend_coverage. The list is non-exhaustive — try a canonical name even if unlisted; a miss returns the served catalog and steers. Banks/insurers often NULL on COGS-based metrics (gross_margin, gross_profit) — use sector alternatives. A CUSTOM multiple (e.g. lease-adjusted EV) = get_stock_price (price leg) + the primitives oper_lease_liabs, ttl_debt, cash_st_invs, ttl_equity, shares_basic. | |
| period_type | No | Q = quarterly, FY = fiscal year, TTM = trailing 12 months. | Q |
| vantage_date | No | As-of vantage (YYYY-MM-DD): restrict the series to periods whose ORIGINAL filing was published on or before this date, and cite the filing that was current then. Omit for the latest. IMPORTANT — this bounds period EXISTENCE and the CITATION; it does NOT reconstruct the value as it stood on that date. Values are the LATEST FILED: if a later filing restated or recast a period (including a later 10-K's comparative columns), that later value is served under the vantage-era citation. A LOOK-AHEAD warning appears only when the period's own filing was later amended; other recasts are NOT flagged. For the value as known at your vantage, call get_xbrl_facts with the accession_number of the latest filing on or before it that reports the period (list_filings takes vantage_date); period_history=true gives each period's value as originally filed. |