Fundamentals — GET /api/fundamentals/{ticker}

Point-in-time (PIT) quarterly fundamentals for a single US equity. Each row carries derived analytics — TTM profitability and capital-return ratios, a cost-of-capital layer, an equity-bridge decomposition — and, in sec_facts, raw line items for the cells whose serving value is SEC XBRL (public). Vendor-sourced cells are not exposed as raw; no forecasts.

Realized historical only. No forecasts, no analyst targets, no consensus/estimate EPS, no buy/sell signals — consistent with the no-investment-advice rule.

What you get

Units: rates and ratios are decimal fractions — roe_ttm of 1.47 is ≈ 147% ROE, and a strict or imputed WACC of 0.05 is 5%. economic_profit is an absolute USD figure (not per-share, not millions). market_cap is a current snapshot in USD, not a per-quarter PIT value.

Point-in-time

A row is returned only where filed_date <= as_of. There is no "latest" shortcut — you always see the panel as it was known on as_of (default: today). filed_date_source is exact (vendor filing date) or approx (period end + 45 days, the 10-Q deadline) when the vendor date is missing.

Strict debt cost and the explicit proxy

cost_of_debt is strictly TTM reported interest expense divided by trusted SEC debt. If debt is positive but reported interest expense is missing or non-positive, strict cost_of_debt and strict wacc remain null — never zero and never silently filled.

In that case, cost_of_debt_imputed may expose a separate PIT-lagged high-quality-market proxy. Its stored credit_spread is the monthly Treasury HQM 10-year corporate spot yield (HQMCB10YR) minus the same-month 10-year Treasury monthly average (GS10). That monthly spread is then added to the separate period-end point-in-time 10-year Treasury rate. The two Treasury observations therefore need not make cost_of_debt_imputed equal hqm_spot_rate.

Month M becomes eligible on day 10 of M+1. hqm_observation_date is the first-of-month reference-month stamp, not a publication timestamp. HQM covers the A/AA/AAA high-quality corporate market; this is not an AAA-only series, an issuer rating, or an issuer-specific bond yield. wacc_imputed uses the same book weights and tax shield as strict WACC. Inspect cost_of_debt_imputation.status: used, not_needed, or unavailable.

For deposit-taking banks and similar financials, neither reported interest expense nor this broad proxy is a bank-specific wholesale-funding estimate.

Abridged example response

{
  "ticker": "AAPL",
  "as_of": "2026-10-07",
  "periods_returned": 1,
  "rows": [
    {
      "period_end_date": "2026-06-30",
      "filed_date": "2026-07-31",
      "filed_date_source": "exact",
      "beta_market": 1.1184,
      "rf_rate": 0.0444,
      "cost_of_equity": 0.1003,
      "cost_of_debt": null,
      "cost_of_debt_imputed": 0.0524,
      "cost_of_debt_imputation": {
        "status": "used",
        "method": "rf_10y_plus_treasury_hqm_10y_spread",
        "risk_free_rate": 0.0444,
        "credit_spread": 0.0080,
        "hqm_spot_rate": 0.0528,
        "hqm_observation_date": "2026-05-01",
        "corporate_series": "HQMCB10YR",
        "treasury_series": "GS10",
        "rating_scope": "A/AA/AAA high-quality market; not issuer-specific"
      },
      "wacc": null,
      "wacc_imputed": 0.0744
    }
  ]
}

This abridged snapshot shows why the fields are parallel: AAPL's strict debt cost and WACC remain null while the explicitly labeled proxy is available. Full responses also include sec_facts, profitability and capital-return ratios, the equity bridge, and the top-level current market_cap. rows is ordered oldest → newest (rows[-1] is the most recent PIT-visible quarter).

Parameters

curl -X GET "https://riskmodels.app/api/fundamentals/AAPL?periods=8&rf_tenor=10y" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY"

from riskmodels import RiskModelsClient

client = RiskModelsClient.from_env()  # reads RISKMODELS_API_KEY
resp = client.get_fundamentals("AAPL", periods=8, erp=0.05, rf_tenor="10y")
latest = resp["rows"][-1]
print(latest["period_end_date"], latest["cost_of_equity"])
print("strict WACC:", latest["wacc"])
print("proxy WACC:", latest["wacc_imputed"])
print("proxy provenance:", latest["cost_of_debt_imputation"])

# Or a tidy one-row-per-quarter DataFrame:
df = client.get_fundamentals("AAPL", periods=8, as_dataframe=True)

Agents with the MCP server connected call the same data through the get_fundamentals tool (same parameters).

Cost-of-capital sensitivity grid (grid=true)

Pass grid=true with erp_grid and rf_tenor_grid to get cost_of_equity, strict wacc, parallel wacc_imputed, and equity-charge economic_profit across every (ERP × tenor) combination for the latest PIT-visible period. Grid-level cost_of_debt_imputed and its provenance are fixed 10-year inputs shared by every cell; the grid tenor changes the cost-of-equity leg, not the debt proxy.

"sensitivity_grid": {
  "period_end_date": "2026-06-30",
  "filed_date": "2026-07-31",
  "erp_values": [0.04],
  "rf_tenor_values": ["1y", "10y", "30y"],
  "tax_rate": 0.21,
  "cost_of_debt_imputed": 0.0524,
  "cost_of_debt_imputation": {
    "status": "used",
    "method": "rf_10y_plus_treasury_hqm_10y_spread",
    "risk_free_rate": 0.0444,
    "credit_spread": 0.0080,
    "hqm_spot_rate": 0.0528,
    "hqm_observation_date": "2026-05-01",
    "corporate_series": "HQMCB10YR",
    "treasury_series": "GS10",
    "rating_scope": "A/AA/AAA high-quality market; not issuer-specific"
  },
  "cells": [
    [
      { "cost_of_equity": 0.0845, "wacc": null, "wacc_imputed": 0.0656, "economic_profit": 138410457998 },
      { "cost_of_equity": 0.0891, "wacc": null, "wacc_imputed": 0.0681, "economic_profit": 137915866038 },
      { "cost_of_equity": 0.0938, "wacc": null, "wacc_imputed": 0.0708, "economic_profit": 137410521895 }
    ]
  ]
}

cells[i][j] pairs erp_values[i] with rf_tenor_values[j] (the example above shows the erp=0.04 row across the three tenors). A strict-null company can therefore have wacc: null beside a non-null, separately labeled wacc_imputed in each cell.

Raw SEC line items — sec_facts

Each row carries a sec_facts object of raw line items, but only for the cells whose serving value is SEC XBRL (public, redistributable). It is keyed by concept — revenue, net_income, operating_income, pretax_income, income_tax_expense, total_assets, total_equity, total_liabilities, retained_earnings, accumulated_oci, cash_from_operations, capital_expenditures, cash_from_investing, cash_from_financing, change_in_cash, dividends_paid, dividends_declared, share_repurchases, share_issuance, share_based_comp, and more — each an object { value, source } where source is us_gaap or ifrs.

A concept is absent for a period when that cell is vendor-sourced (not redistributable) or empty. Coverage is per filer and contiguous in time: from the quarter a filer adopted XBRL (generally 2009+) forward, most concepts are SEC-served; earlier periods are vendor-sourced and so absent from sec_facts. Values are as-originally-reported.

"sec_facts": {
  "revenue":       { "value": 111184000000, "source": "us_gaap" },
  "net_income":    { "value": 29578000000,  "source": "us_gaap" },
  "total_equity":  { "value": 106491000000, "source": "us_gaap" },
  "dividends_paid":{ "value": 3822000000,   "source": "us_gaap" }
}

Capital-return ratios

payout_ratio, retention_ratio (= 1 - payout, the reinvestment-rate proxy), buyback_ratio, total_payout_ratio (dividends + buybacks / net income; can exceed 1 in a heavy-buyback year), and sustainable_growth (= retention_ratio × roe_ttm) are TTM. Dividend basis is cash paid; all are null when trailing-4-quarter net income is <= 0.

Equity bridge

equity_bridge_residual is the plug that closes the equity roll-forward by construction (total_equity_t − total_equity_{t-1} = tagged components + residual). It is a decomposition aid, not a measured line, and is frequently large. equity_bridge_inputs lists the components that backed it — a component missing from the list means its movement is inside the residual, not that it was zero (e.g. a filer that does not tag dividends has its dividends in the residual). For modelling, anchor on retained_earnings.

Licensing & precision

Raw line items appear only in sec_facts, per the SEC-cell rule above; vendor-sourced raw values are not returned. gross_margin / operating_margin come back null pending inputs, and market_cap is a current snapshot, not point-in-time per quarter.

Numeric line items are stored at ~7 significant figures (float32) — suitable for analysis, not for cent-level reconciliation. (Share counts are exempt once the exact-precision store update lands.)

Caveats

• Valuation beta. beta_market in this endpoint is the long-window (~60-month monthly, Vasicek-shrunk) valuation beta used by the CAPM layer, not the short-half-life hedging beta on the daily risk surface (see ERM3 engine). For defensive names it can still be low or negative, so cost_of_equity can fall below the risk-free rate.
• market_cap is current, not PIT. The top-level market_cap is today's snapshot; the per-row market_cap is null. Do not read it as the market cap at that quarter end.
• Book-weight WACC. Strict wacc and wacc_imputed use balance-sheet (book) weights. Market-value weights are the textbook convention; compute them yourself if you have market cap.
• Strict and proxy are not interchangeable. Prefer strict reported-data fields when available. If you use wacc_imputed, label it as the PIT-lagged high-quality-market proxy and carry its provenance; do not present it as Apple's or any issuer's reported borrowing cost.
• ERP is a request assumption. The endpoint has no stored house ERP opinion. It uses the documented 0.05 default if omitted; pass erp explicitly (or use grid) and state the value. Pair a short rf_tenor (3m/1y) with a bill-basis ERP or cost of capital is understated.
• Coverage starts ~2009 for most filers; pre-2009, small-cap, and recently-IPO'd names are thin. Missing fields are null, not row-dropped.

Error responses

Pricing

$0.02 / call, per symbol per call. There is no batch variant — one ticker per request.

Related

• API guide — endpoint map and workflow
• OpenAPI reference — full request/response schema for /fundamentals/{ticker}
• ERM3 engine — the model hierarchy behind the valuation betas
• Methodology — the hierarchical model and factor set