---
title: "Full returns decomposition (L1/L2/L3 + optional Lstar)"
method: GET
path: "/returns-decomposition"
tags: ["Risk Metrics"]
---

# Full returns decomposition (L1/L2/L3 + optional Lstar)

`GET /returns-decomposition`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/returns-decomposition`
- Auth: HTTP bearer

One-call daily return decomposition: gross return plus L1/L2/L3 factor,
combined-factor, and residual return series from ds_erm3_returns zarr.
Set `include_lstar=true` or `dispatch=lstar` to append Lstar level and
Lstar-dispatched residual return per date (prefers materialized zarr
lstar_rr/lstar_level when present; otherwise derives from marginal ERs).

## Query parameters

- `ticker` string, required
- `market_factor_etf` string
- `years` integer
- `include_lstar` boolean
- `dispatch` 'lstar'
- `threshold` number, float

## Response `200`

Returns decomposition time series

- ReturnsDecompositionResponse: Daily gross return and L1/L2/L3 factor, combined-factor, and residual return series from ds_erm3_returns (zarr SSOT). Optional Lstar dispatch adds per-date recommended hedge level and Lstar residual return.
  - `ticker` string
  - `dates` string[]
  - `gross_return` number[]
  - `l1_factor_return` number[]
  - `l2_factor_return` number[]
  - `l3_factor_return` number[]
  - `l1_combined_factor_return` number[]
  - `l2_combined_factor_return` number[]
  - `l3_combined_factor_return` number[]
  - `l1_residual_return` number[]
  - `l2_residual_return` number[]
  - `l3_residual_return` number[]
  - `lstar` string[]: Present when include_lstar=true or dispatch=lstar.
  - `lstar_residual_return` number[]
  - `threshold_used` number, float: Marginal ER threshold used for Lstar dispatch (default 0.01).
  - `market_factor_etf` string
  - `universe` string
  - `data_source` string

## Other responses

- `400`: Invalid request
- `404`: Ticker not found
- `500`: Internal error

---

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