---
title: "(internal/legacy) Latest risk metrics snapshot"
method: GET
path: "/metrics/{ticker}"
tags: ["Risk Metrics"]
---

# (internal/legacy) Latest risk metrics snapshot

`GET /metrics/{ticker}`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/metrics/{ticker}`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://riskmodels.app/oauth/authorize`, token URL `https://riskmodels.app/api/oauth/token`, scopes: `mcp:read`)

**Per Snapshot Architecture v3, prefer `POST /snapshot` with `type: "ticker"` for new clients.** This endpoint remains callable as an internal building block.
Returns the latest V3 daily metrics for the ticker. Numeric fields are under the `metrics` object using abbreviated keys (`l3_mkt_hr`, `l3_sec_hr`, `l3_sub_hr`, `l3_mkt_er`, `l3_res_er`, `vol_23d`, etc.). The observation date is `teo`. Optional `display` maps keys to human-readable labels.

**Authentication:** Required (API Key or OAuth2)
**Billing:** $0.005 per request (deducted from account balance)
**Rate Limit:** 60 requests/minute (default)

## Path parameters

- `ticker` string, required

## Response `200`

Latest metrics snapshot.

- MetricsSnapshotResponse: Wire response for `GET /metrics/{ticker}`. Numeric fields live under `metrics`; `teo` is the observation date (V3 time-end).
  - `symbol` string, required: Canonical symbol key in V3 registry.
  - `ticker` string, required
  - `teo` string, date, required: Latest observation date for the metrics row.
  - `periodicity` string, required
  - `metrics` MetricsV3, required: V3 metric keys as returned inside `GET /metrics/{ticker}` under the `metrics` property. Suffixes: `_mkt` market, `_sec` sector, `_sub` subsector, `_res` residual. Hedge ratios (HR) are dollars of ETF to trade per $1 of stock; explained risk (ER) are variance fractions (0–1). Keys `l1_cfr`–`l3_rr` are daily simple returns from returns decomposition: - `*_cfr` (combined factor return) is CUMULATIVE through the level: `l1_cfr = l1_fr`, `l2_cfr = l1_fr + l2_fr`, `l3_cfr = l1_fr + l2_fr + l3_fr`. - `*_fr` (factor return, INCREMENTAL) is each level's own contribution — `l2_fr` is what the sector factor adds on top of L1 alone, `l3_fr` is what the subsector factor adds on top of L1+L2. Use these for stacked-bar decomposition charts or for agent-side attribution ("what drove today's return at each level?"). - `*_rr` (residual return) is what's left after factors through that level — `gross_return ≈ l3_cfr + l3_rr`. Keys `lstar_rr` and `lstar_level` carry the Lstar-dispatched residual return and the level that was picked, per-(teo, symbol), by ERM3's canonical selector. Use these when you want "the best residual" — the idiosyncratic leg at the same hedge depth as production HR/ER. For the legacy marginal-ER rule at a chosen threshold, hit `GET /lstar?threshold=`. None of these are ER fields and none come from hedge-weight explainability. Keys `l1_mkt_beta`, `l2_sec_beta`, `l3_sub_beta` are dimensionless hierarchical regression betas (one per level: 1 for L1, 2 for L2, 3 for L3 — though only the L*-introduced new factor is stored at each level). These are NOT the same as hedge ratios — betas are regression coefficients, hedge ratios are dollar-notional ratios.
    - `vol_23d` number, float, nullable: Annualised realised volatility (23 trading days), decimal fraction.
    - `vol_252d_ann` number, float, nullable: Annualised realised volatility over the trailing ~252 trading days, decimal fraction. Computed on demand from daily `returns_gross` and cached per (symbol, data_as_of); matches the horizon of 1y return cascades so callers can size positions on a common basis. Null when fewer than 20 usable daily observations are available.
    - `price_close` number, float, nullable
    - `market_cap` number, float, nullable
    - `stock_var` number, float, nullable
    - `l1_mkt_hr` number, float, nullable
    - `l1_mkt_er` number, float, nullable
    - `l1_res_er` number, float, nullable
    - `l1_cfr` number, float, nullable: Daily simple combined factor return through L1 (market), decimal (same convention as returns_gross). From returns-decomposition zarr (ds_erm3_returns), not hedge weights. Not a variance fraction — unlike l1_mkt_er. At L1 this is equal to l1_fr (there's no level below market to add on top of).
    - `l1_fr` number, float, nullable: Daily simple factor return for L1 (market) — the INCREMENTAL contribution of the market factor alone. At L1 this equals l1_cfr. Use `l1_fr`/`l2_fr`/`l3_fr` for stacked-bar factor decomposition charts and for per-level P&L attribution.
    - `l1_rr` number, float, nullable: Daily simple residual return at L1 (decimal). Not l1_res_er (explained risk).
    - `l2_mkt_hr` number, float, nullable
    - `l2_sec_hr` number, float, nullable
    - `l2_mkt_er` number, float, nullable
    - `l2_sec_er` number, float, nullable
    - `l2_res_er` number, float, nullable
    - `l2_cfr` number, float, nullable: Daily simple combined factor return through L2 (market + sector), decimal. Equals l1_fr + l2_fr.
    - `l2_fr` number, float, nullable: Daily simple factor return for L2 (sector) — the INCREMENTAL contribution the sector factor adds on top of L1 (market). For a sector-led rally this is the number to highlight in charts.
    - `l2_rr` number, float, nullable: Daily simple residual return at L2 (decimal).
    - `l3_mkt_hr` number, float, nullable
    - `l3_sec_hr` number, float, nullable
    - `l3_sub_hr` number, float, nullable
    - `l3_mkt_er` number, float, nullable
    - `l3_sec_er` number, float, nullable
    - `l3_sub_er` number, float, nullable
    - `l3_res_er` number, float, nullable: Idiosyncratic variance fraction at L3.
    - `l3_cfr` number, float, nullable: Daily simple combined factor return through L3 (market + sector + subsector), decimal. Equals l1_fr + l2_fr + l3_fr.
    - `l3_fr` number, float, nullable: Daily simple factor return for L3 (subsector) — the INCREMENTAL contribution the subsector factor adds on top of L1 + L2. Completes the three-level stacked decomposition: l1_fr + l2_fr + l3_fr + l3_rr ≈ gross_return.
    - `l3_rr` number, float, nullable: Daily simple residual return at L3 (decimal). Distinct from l3_residual_er (ER).
    - `lstar_rr` number, float, nullable: Daily simple residual return at the Lstar-dispatched level — L1→market, L2→sector, L3→subsector residual. Materialized as `residual_return.sel(level='lstar')` in `ds_erm3_returns` by ERM3's canonical selector. For the legacy marginal-ER rule at a chosen threshold use `GET /lstar?threshold=`.
    - `lstar_level` 1 | 2 | 3 | null, nullable: Which cascade level ERM3's canonical selector (the cost-aware GBM once enabled) dispatched to per (teo, symbol): 1 = L1 (market only), 2 = L2 (sector), 3 = L3 (subsector). `null` = no recommendation (both L2 and L3 ER are NaN — pre-IPO / delisted / masked). Maps from the uint8 `lstar_level` companion var in `ds_erm3_returns`, with 0 → null at the API boundary. For a custom threshold use `GET /lstar` which returns the level as a string.
    - `l1_mkt_beta` number, float, nullable: Hierarchical regression beta to the symbol's L1 market factor (always SPY). Dimensionless (units of stock-return per unit of factor-return). One value per symbol from the L1 model. Sourced from `ds_erm3_betas` `factor_beta` at `fact_level=1`. NOT a hedge ratio (which is dollar-notional). NOT classical univariate beta — see `SEMANTIC_ALIASES.md` for the multivariate-vs-univariate convention.
    - `l2_sec_beta` number, float, nullable: Hierarchical regression beta to the symbol's L2 sector factor — the symbol's specific sector ETF (e.g. XLK for AAPL, XLF for JPM). Dimensionless. From `ds_erm3_betas` `factor_beta` at `fact_level=2`. Null when the symbol has no sector classification.
    - `l3_sub_beta` number, float, nullable: Hierarchical regression beta to the symbol's L3 subsector factor — the symbol's specific subsector ETF (e.g. RSPT for AAPL, KBE for JPM). Dimensionless. From `ds_erm3_betas` `factor_beta` at `fact_level=3`. Null when the symbol has no subsector classification.
  - `display` object, required: Optional display labels for metric keys (e.g. UI column titles).
  - `meta` object, required
    - `sector_etf` string, nullable
    - `asset_type` string, nullable
  - `hedge_levels` HedgeLevelsBlock: Canonical L1/L2/L3 hedge snapshots (additive on metrics, decompose, batch success rows). Prefer this block over parsing flat `l*_mkt_hr` wire keys when comparing cascade levels.
    - `L1` LevelHedgeSnapshot, required: One hierarchical level (L1, L2, or L3) as a standalone hedge solution — HR and ER for each populated leg plus resolved ETF mnemonics. Null legs indicate that leg is not part of this level.
      - `market_hr` number, nullable, required: Dollar-ratio HR (ETF notional per $1 stock).
      - `sector_hr` number, nullable, required
      - `subsector_hr` number, nullable, required
      - `market_er` number, nullable, required: Explained-risk variance fraction where defined for this level.
      - `sector_er` number, nullable, required
      - `subsector_er` number, nullable, required
      - `residual_er` number, nullable, required
      - `hedge_etfs` object, required
        - `market` string, required
        - `sector` string, nullable, required
        - `subsector` string, nullable, required
    - `L2` LevelHedgeSnapshot, required: One hierarchical level (L1, L2, or L3) as a standalone hedge solution — HR and ER for each populated leg plus resolved ETF mnemonics. Null legs indicate that leg is not part of this level.
      - `market_hr` number, nullable, required: Dollar-ratio HR (ETF notional per $1 stock).
      - `sector_hr` number, nullable, required
      - `subsector_hr` number, nullable, required
      - `market_er` number, nullable, required: Explained-risk variance fraction where defined for this level.
      - `sector_er` number, nullable, required
      - `subsector_er` number, nullable, required
      - `residual_er` number, nullable, required
      - `hedge_etfs` object, required
        - `market` string, required
        - `sector` string, nullable, required
        - `subsector` string, nullable, required
    - `L3` LevelHedgeSnapshot, required: One hierarchical level (L1, L2, or L3) as a standalone hedge solution — HR and ER for each populated leg plus resolved ETF mnemonics. Null legs indicate that leg is not part of this level.
      - `market_hr` number, nullable, required: Dollar-ratio HR (ETF notional per $1 stock).
      - `sector_hr` number, nullable, required
      - `subsector_hr` number, nullable, required
      - `market_er` number, nullable, required: Explained-risk variance fraction where defined for this level.
      - `sector_er` number, nullable, required
      - `subsector_er` number, nullable, required
      - `residual_er` number, nullable, required
      - `hedge_etfs` object, required
        - `market` string, required
        - `sector` string, nullable, required
        - `subsector` string, nullable, required
    - `recommended_level` 'L1' | 'L2' | 'L3', nullable: Economic recommendation when emitted (user-segment hedge gate).
    - `statistical_lstar` 'L1' | 'L2' | 'L3', nullable: Orthogonal cascade statistical layer pick.

## Other responses

- `401`: Missing or invalid Bearer token.
- `402`: Insufficient balance.
- `404`: Symbol not found or no metrics row (see error message).
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/riskmodels/apis/riskmodels-api.md) · [All operations](https://skmtc.dev/riskmodels/apis/riskmodels-api/llms.txt) · [OpenAPI document](https://skmtc.dev/riskmodels/apis/riskmodels-api/revisions/1a034cad408a?raw)