RiskModels V2 API Documentation

Overview

The RiskModels API (V2) provides programmatic access to institutional-grade equity risk analysis. The system uses a long-form Entity-Attribute-Value (EAV) schema for historical time-series data, enabling maximum flexibility for financial metrics.

Base URL: https://riskmodels.net/api

Response metadata: Time-series endpoints include _metadata with data_as_of and model_version for reproducibility.

Core Endpoints

1. /api/tickers

Search and list all available symbols in the RiskModels universe.

• GET /api/tickers?array=ticker: List all ticker symbols.
• GET /api/tickers?search=QUERY: Search for a ticker by symbol or company name.
• GET /api/tickers?mag7=true: Returns only Magnificent 7 tickers (high performance).

2. /api/metrics/[ticker]

Get the latest risk metrics snapshot for a specific ticker.

• GET /api/metrics/AAPL: Latest volatility, hedge ratios, and explained risk.

3. /api/ticker-returns

Fetch historical daily returns and hierarchical hedge ratios.

• GET /api/ticker-returns?ticker=NVDA&years=3: 3 years of daily returns with L3 market, sector, and subsector hedge ratios.
• Format: Add ?format=parquet or ?format=csv for bulk downloads (default: JSON).
• Response: Includes data, meta, and _metadata (model_version, data_as_of).

4. /api/returns and /api/etf-returns

Stock and ETF returns time series (daily).

• GET /api/returns?ticker=AAPL&years=1: Daily gross returns for a stock.
• GET /api/etf-returns?ticker=SPY&years=5: Daily gross returns for an ETF.
• Format: ?format=parquet or ?format=csv supported.

5. /api/estimate

Pre-flight cost estimate (free to call).

• POST /api/estimate

  { "endpoint": "ticker-returns", "params": { "ticker": "NVDA", "years": 5 } }
  

• Returns estimated_cost_usd and related fields.

6. /api/l3-decomposition

Detailed hierarchical risk decomposition history.

• GET /api/l3-decomposition?ticker=TSLA&from=2024-01-01: Time-series of HR and ER metrics at all three factor levels.

7. /api/batch/analyze

Efficiently analyze multiple positions in a single call.

• POST /api/batch/analyze

  {
    "tickers": ["AAPL", "MSFT", "GOOGL"],
    "metrics": ["returns", "hedge_ratios", "full_metrics"],
    "years": 1
  }
  

8. /api/heatmap

Retrieve market-wide data for treemap visualizations.

• GET /api/heatmap?limit=500: Top 500 stocks with latest returns and market caps.

Data Schema (V2)

Table: symbols (Master Registry)

Stores metadata and latest cached metrics for all securities.

• ticker: TEXT (PK)
• asset_type: ENUM ('stock', 'etf', 'index')
• latest_teo: DATE
• latest_vol: REAL
• latest_er_total: REAL
• latest_hr_mkt: REAL
• metadata: JSONB (company_name, sector, industry, sector_etf)
• latest_metrics: JSONB (additional daily snapshots)

Table: security_history (Time-Series)

Stores historical values in EAV format.

• symbol: TEXT (FK to symbols)
• teo: DATE
• metric_key: TEXT (e.g., 'return', 'L3_market_HR')
• value: REAL
• periodicity: ENUM ('daily', 'monthly')

Key Metrics Reference

| Metric Key | Description | Unit | |------------|-------------|------| | return | Daily log return | Decimal | | L3_market_HR | Market (SPY) hedge ratio | Ratio | | L3_sector_HR | Sector (GICS) hedge ratio | Ratio | | L3_subsector_HR | Subsector hedge ratio | Ratio | | L3_market_ER | Risk explained by Market | 0.0 - 1.0 | | L3_residual_risk | Idiosyncratic risk remaining | 0.0 - 1.0 |

Last Updated: March 18, 2026