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, 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.

Example response

{
  "ticker": "AAPL",
  "as_of": "2026-07-10",
  "periods_returned": 8,
  "rows": [
    {
      "period_end_date": "2026-03-31",
      "filed_date": "2026-05-01",
      "filed_date_source": "exact",
      "roe_ttm": 1.4669,
      "roa_ttm": 0.3402,
      "fcf_margin": 0.2965,
      "leverage_ratio": 0.8499,
      "beta_market": 1.0012,
      "beta_sector": -0.3954,
      "beta_subsector": -0.1920,
      "beta_source": "in-universe",
      "rf_rate": 0.0430,
      "cost_of_equity": 0.0931,
      "cost_of_debt": null,
      "wacc": 0.0503,
      "economic_profit": 146300933417.0,
      "gross_margin": null,
      "operating_margin": null,
      "market_cap": null
    }
  ],
  "market_cap": { "value": 4596707098624, "basis": "current_snapshot" }
}

rows is ordered oldest → newest (rows[-1] is the most recent PIT-visible quarter). Each row also carries sec_facts (raw SEC-sourced line items, per cell — see below), the capital-return ratios, and the equity-bridge fields. gross_margin / operating_margin and the per-row market_cap are null (see below); the top-level market_cap is the current snapshot.

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"], latest["economic_profit"])

# 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 / wacc / economic_profit across every (ERP × tenor) combination for the latest PIT-visible period — one read, no hardcoded ERP opinion:

"sensitivity_grid": {
  "period_end_date": "2026-03-31",
  "erp_values": [0.04, 0.05, 0.06],
  "rf_tenor_values": ["1y", "10y", "30y"],
  "tax_rate": 0.21,
  "cells": [
    [
      { "cost_of_equity": 0.0768, "wacc": 0.0415, "economic_profit": 148027338416 },
      { "cost_of_equity": 0.0830, "wacc": 0.0449, "economic_profit": 147367094129 },
      { "cost_of_equity": 0.0888, "wacc": 0.0480, "economic_profit": 146749446568 }
    ]
  ]
}

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).

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

• Conditional betas, not textbook CAPM. beta_market is a short-half-life conditional beta from the ERM3 L3 cascade (see ERM3 engine), so cost_of_equity is closer to a current expected return than a long-run Damodaran-style cost of equity. For defensive names the beta can be low or negative, so cost_of_equity can fall below the risk-free rate — a property of the conditional beta, not an error.
• 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. WACC uses balance-sheet (book) weights. Market-value weights are the textbook convention; compute them yourself if you have market cap.
• ERP is never stored. The endpoint has no house ERP opinion — you pass erp (and optionally grid) and own the assumption. 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 — where the cascade betas come from
• Methodology — the hierarchical model and factor set