---
title: "Macro factor daily return series"
method: GET
path: "/macro-factors"
tags: ["Risk Metrics"]
---

# Macro factor daily return series

`GET /macro-factors`

## Request

- Base URL: `https://riskmodels.app/api`
- URL: `https://riskmodels.app/api/macro-factors`
- 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`)

Returns long-format rows from Supabase `macro_factors` (`factor_key`, `teo`, `return_gross`) for the requested date range. No stock ticker is required. Omit `factors` to use all ten canonical keys (`inflation`, `term_spread`, `short_rates`, `credit`, `oil`, `gold`, `usd`, `volatility`, `bitcoin`, `vix_spot`); aliases such as `btc` → `bitcoin`, `xau`/`gld` → `gold`, and legacy v1 names (`dxy` → `usd`, `vix` → `vix_spot`, `ust10y2y` → `term_spread`) normalize automatically. Default date range: from five calendar years before `end` through `end` (UTC date); default `end` is today. Maximum span: 20 years. Cost: $0.005 per request. JSON Schema (MCP): https://riskmodels.app/schemas/macro-factors-series-v1.json

## Query parameters

- `factors` string
- `start` string, date
- `end` string, date

## Response `200`

Macro factor rows and lineage metadata.

- MacroFactorsSeriesResponse
  - `factors_requested` string[], required
  - `start` string, date, required
  - `end` string, date, required
  - `row_count` integer, required
  - `series` MacroFactorsSeriesRow[], required
    - `factor_key` string, required
    - `teo` string, date, required
    - `return_gross` number, float, nullable
    - `metadata` object: Present only when non-empty in `macro_factors.metadata`.
  - `warnings` string[], required
  - `_metadata` RiskMetadata: Lineage and provenance metadata for all data responses. Included in response body as _metadata and as X-Risk-* headers.
    - `model_version` string: ERM3 model version (e.g. ERM3-L3-v30).
    - `data_as_of` string, date: Latest trading date reflected in the response (model outputs / latest snapshot).
    - `factor_set_id` string: Factor set identifier.
    - `universe_size` integer: Number of stocks in the universe.
    - `wiki_uri` string, uri: Methodology documentation URL.
    - `factors` string[]: L3 factor ETF tickers (market + 11 sectors).
    - `data_source` 'zarr': Present on history-style JSON responses. Always `"zarr"` as of the pure-Zarr SSOT cutover: all historical time series (daily metrics, hedge weights, returns decomposition, rankings) are served from consolidated Zarr stores on GCS. The Supabase `security_history` table has been removed; the legacy `"supabase"` value is retained in clients only for backwards compatibility.
    - `range` string[]: Optional inclusive ISO date bounds of the returned history window when `data_source` is set.
  - `_agent` object
    - `latency_ms` integer
    - `request_id` string

## Other responses

- `400`: Invalid query (date range, factors, or span).
- `401`: Missing or invalid Bearer token.
- `402`: Insufficient balance.
- `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)