Metric History
get_metric_historyTime series for one metric across fiscal periods. 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.
⚠ 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")
Also serves NON-XBRL operating KPIs (LLM-extracted from earnings releases), almost all QUARTERLY — coverage varies by KPI. Besides the ids on metric_id: gross_booking_value, take_rate (marketplaces), revpar, occupancy_rate (lodging/REIT), passenger_load_factor, prasm, casm (airlines), oil_production, and more.
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. Operating KPIs (non-XBRL, mostly quarterly), most-covered first: net_interest_margin, return_on_average_assets, return_on_average_equity, nonperforming_assets_to_total_assets, nonperforming_loans_to_total_loans, allowance_for_credit_losses_to_total_loans, loan_to_deposit_ratio, net_charge_offs_to_average_loans, common_equity_tier_1_capital_ratio, tier_1_leverage_ratio, tier_1_capital_ratio, total_capital_ratio, return_on_average_tangible_common_equity, net_leverage_ratio, nonperforming_loan_ratio, liquidity_coverage_ratio, net_stable_funding_ratio, combined_ratio, loss_ratio, expense_ratio, policies_in_force, arr, recurring_revenue, remaining_performance_obligations, organic_revenue_growth, cancellation_rate, subscribers, arpu, store_count, same_store_sales. Both lists are non-exhaustive — try a canonical name even if unlisted; a miss returns the full 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. If a later filing restated a period, the restated value is what is served, and the response carries an explicit LOOK-AHEAD warning naming the affected periods. For a true as-originally-filed series use get_xbrl_facts with period_history=true. |