RiskModels

Use when you have a long-only book of up to 100 names and want its holdings-weighted L1, L2 and L3 hedge ratios, or the ETF hedge notionals for dollar positions. Not for books with shorts or more than 100 names (use riskmodels_portfolio_exposure) or a variance decomposition with return attribution (use riskmodels_get_portfolio_risk_snapshot). Returns, from POST /batch/analyze, portfolio hedge levels at L1, L2 and L3 with per-ticker detail. Only when every position is given in dollars does it also return the ETF hedge notionals at hedge_level (set by level, default L3), by ticker and summed by ETF; with weights, level is ignored. End-of-day data, refreshed after each US market close. Price: $0.015 per position, minimum $0.03 per call.

Use when you want 2-100 stocks side by side on market, sector, subsector and residual risk. Not for one stock (use riskmodels_decompose) or a weighted portfolio (use riskmodels_analyze_portfolio). Returns, from POST /batch/analyze, each ticker's explained-risk shares and hedge ratios by layer, with chart-ready data. End-of-day data, refreshed after each US market close. Price: $0.015 per ticker, minimum $0.03 per call.

Use when you want one stock's risk split into market, sector, subsector and residual layers, or the ETF hedge legs for a dollar position in it. Not for several stocks (use riskmodels_compare) or a portfolio (use riskmodels_analyze_portfolio). Returns, from POST /decompose, each layer's explained-risk share, hedge ratio and hedge ETF, chart-ready data and a one-line summary; with dollars it returns the ETF hedge notionals for that position at each level (hedge ratio times dollars). End-of-day data, refreshed after each US market close. Price: $0.005 per call.

Use when you want a book's realized residual return over a date window attributed to stock selection versus drift. Not for current risk or hedges (use riskmodels_portfolio_exposure). Returns, from POST /cohorts/pnl-decomposition, selection (from holding names that beat their cohort's average residual) and drift (from net exposure to the cohort average), which sum exactly to the total; weights are held constant over the window and not normalized, a short is a negative weight, and positions that cannot be mapped to a cohort are listed in coverage.dropped. Historical attribution on end-of-day data. Price: $0.25 per call.

Use when you want to compare a fund, 13F filer or ETF portfolio with a benchmark: active share and the largest active weights. Not for the subject's own holdings (use riskmodels_get_fund, riskmodels_get_filer or riskmodels_get_etf). Returns, from GET /data/benchmark-fit, active share, active-weight RMS (a coarse tracking-error proxy), overlap, and the largest over- and underweights at a common date. Benchmarks: ff_own (free-float-cap weights of the subject's own holdings), the large and small style cells (cell_large-value, cell_large-blend, cell_large-growth, cell_small-value, cell_small-blend, cell_small-growth), or all (every available benchmark for the subject). Holdings dates follow the latest filings; weights use end-of-day prices. Price: $0.02 per call.

Use when you want cross-sectional residual statistics for SPY and the 11 GICS sector SPDR cohorts, on one date or as a time series. Not for one stock's peers (use riskmodels_get_peers) or one stock's rank (use riskmodels_get_rankings). Returns, from GET /cohorts (one date) or GET /cohorts/series (series=true), residual_mean, residual_sd, mean_pairwise_corr, n_names and n_effective by default, more on request. ERM3 residuals are fitted without an intercept, so residual_mean is not zero; link_fit_resid_sd is the residual standard deviation of the 252-day link regression, a fit-quality measure rather than a standard error. Subsector cohorts are not available. End-of-day data, refreshed after each US market close. Price: $0.04 for one date, $0.15 for a series.

Use when you want one ETF's registry metadata and portfolio surface, and optionally its largest holdings. Not for finding an ETF ticker (use riskmodels_search) or the ETF's daily returns (use riskmodels_get_returns). Returns { snapshot, holdings }: snapshot from GET /data/etf/{ticker}; holdings, only when holdings_top is set, from GET /data/etf/{ticker}/holdings. Holdings follow the latest published holdings file; registry refreshed end-of-day. Free (no per-call charge).

Use when you need macro factor return series (inflation, term spread, short rates, credit, oil, gold, the dollar, volatility, bitcoin, VIX) or the trailing returns of SPY and the 11 GICS sector SPDR ETFs. Not for a stock's correlation with those factors (use riskmodels_get_macro_correlation) or one ETF's daily return series (use riskmodels_get_returns). kind macro returns daily total returns over a date range (GET /macro-factors); kind sector_etf returns closing price and trailing 1, 21, 63 and 252-day total returns on one date (GET /etf/factor-returns). End-of-day data, refreshed after each US market close. Price: $0.005 per call (macro) or $0.02 per call (sector_etf).

Use when you want a 13F filer's profile, latest metrics and concentration, and optionally its largest holdings. Not for finding the bw_filer_id (use riskmodels_search) or comparing the book with a benchmark (use riskmodels_get_benchmark_fit). Returns { snapshot, holdings }: snapshot from GET /13f/filers/{bw_filer_id}/snapshot (registry details, latest metrics, concentration); holdings, only when holdings_top is set, from GET /13f/filers/{bw_filer_id}/holdings with the source filing's accession_number, filing_type (13F-HR, 13F-HR/A, 13F-NT) and amendment_type (ORIGINAL, RESTATEMENT, NEW_HOLDINGS or UNKNOWN; null on panels published before filing vintages were stored). Holdings follow the latest 13F filing; metrics use end-of-day prices. Price: $0.05, plus $0.02 when holdings are requested.

Use when you want a US mutual fund's profile, return decomposition, hedge ratios and style-box ranks, and optionally its full holdings. Not for finding the bw_fund_id (use riskmodels_search) or comparing the fund with a benchmark (use riskmodels_get_benchmark_fit). Returns { snapshot, holdings }: snapshot from GET /funds/snapshot/{bw_fund_id} (registry details, latest return decomposition and diagnostics, top 25 holdings, L1/L2/L3 ETF hedge ratios, a 12-month portfolio time series and the fund's rank within its style box on each ranked metric); holdings, only when holdings_limit is set, from GET /funds/{bw_fund_id}/holdings (latest filed SEC N-PORT report, ranked by absolute market value, signed weights, long/short/net/gross totals and ticker coverage). Holdings follow the latest N-PORT filing; metrics use end-of-day prices. Price: $0.05, plus $0.02 when holdings are requested.

Use when you need point-in-time quarterly fundamentals or CAPM cost of capital for one stock. Not for risk or hedge numbers (use riskmodels_get_stock_snapshot). Returns, from GET /fundamentals/{ticker}: TTM profitability and capital-return ratios, leverage, ERM3 valuation betas, cost_of_debt and wacc from reported data, separately labelled cost_of_debt_imputed and wacc_imputed from a market proxy (10-year Treasury plus a high-quality corporate spread, not issuer-specific), economic profit, an equity-bridge decomposition and SEC line items (sec_facts). A quarter is included only if it was filed on or before as_of. grid=true adds an ERP x Treasury-tenor table of cost of equity, wacc, wacc_imputed and economic profit for the latest period. Realized history only, no forecasts; filings are picked up end-of-day. Price: $0.02 per call.

Use when you want to know how one stock's returns co-move with macro factors such as rates, credit, oil, the dollar or volatility. Not for the macro factor return series themselves (use riskmodels_get_factor_returns). Returns, from POST /correlation, Pearson or Spearman correlations over a trailing window, using the L3 residual return by default. End-of-day data, refreshed after each US market close. Price: $0.01 per call.

Use when the request concerns the caller's own linked brokerage book. Not for a book typed into the conversation (use riskmodels_analyze_portfolio or riskmodels_portfolio_exposure). Returns the caller's positions from their default riskmodels.net portfolio (Alpaca Connect, Connect Trade or Plaid): ticker, quantity, market value and weight of each position, has_shorts, and the same book in three shapes: for_analysis (positive weights), for_hedge (positive dollar values) and for_exposure (signed dollars, short < 0). Returns an empty book when no brokerage is linked. Read-only; it does not place orders. Positions are as of the portal's last brokerage sync. Free (no REST charge). No inputs.

Use when you want the stocks that share a stock's subsector ETF or sector ETF. Not for cohort-level residual statistics (use riskmodels_get_cohorts). Returns, from GET /peers, the peer list ordered by market cap with each peer's market cap. End-of-day data, refreshed after each US market close. Price: $0.005 per call.

Use when you want a long-only portfolio's risk decomposed into market, sector, subsector and residual variance, with diversification analytics and return attribution. Not for long/short books (use riskmodels_portfolio_exposure) or ETF hedge notionals (use riskmodels_analyze_portfolio). Returns, from POST /snapshot (the canonical portfolio snapshot), the L3 variance decomposition, per-position L3 hedge ratios, diversification analytics with sector and subsector ETF correlations, frozen-weight daily return attribution, cumulative return and drawdown over lookback_days, and a risk summary with dominant drivers and concentration flags. End-of-day data, refreshed after each US market close. Price: $1.25 per call.

Use when you want one stock's percentile rank within the universe, its sector or its subsector on a risk or return metric. Not for screening the whole universe (use riskmodels_screen_rankings). Returns, from GET /rankings/{ticker}, the stock's rank and percentile for the metric and window. Metrics: subsector_residual, sector_residual, gross_return, mkt_cap, er_l1, er_l2 or er_l3. Windows: 1d, 21d, 63d, 252d. End-of-day data, refreshed after each US market close. Price: $0.005 per call.

Use when you need daily residual (stock-specific) returns and the recommended hedge depth (L1 market, L2 sector or L3 subsector) for 1-100 stocks. Not for the full factor split of each day's return (use riskmodels_get_return_attribution) or a mean-reversion signal on a basket (use riskmodels_get_residual_signal). Returns, per ticker, the recommended depth by date, the hedge ratios at that depth and the daily residual return series. One ticker is served by GET /lstar; 2-100 tickers by POST /batch/lstar. Without threshold the depth is the one ERM3 publishes; with threshold it is the simplest depth whose marginal explained risk exceeds the threshold. End-of-day data, refreshed after each US market close. Price: one ticker $0.02 plus $0.01 per year beyond the first; 2-100 tickers $0.015 per ticker plus $0.0075 per ticker per year beyond the first, minimum $0.03 per call.

Use when you want the L3 residual mean-reversion signal aggregated over a basket of 1-100 stocks. Not for the residual return series themselves (use riskmodels_get_residual_returns). Returns, from POST /signals/residual-reversion/basket, the basket-aggregated signal, with optional weights and a minimum signal-quality quintile; it describes recent residual moves and is not a forecast. End-of-day data, refreshed after each US market close. Price: $0.02 per call.

Use when you need each day's return of one stock split into market, sector and subsector factor returns and the residual (stock-specific) return. Not for raw total returns (use riskmodels_get_returns) or residual returns for many stocks (use riskmodels_get_residual_returns). Returns, from GET /returns-decomposition, the daily gross return and its additive components (decimal returns); include_lstar adds the residual series at each day's recommended hedge depth. End-of-day data, refreshed after each US market close. Price: $0.04 per call plus $0.01 per year of history beyond the first.

Use when you need the daily dividend-adjusted total returns of one US stock or ETF over 1-15 years. Not for returns split into factor and residual parts (use riskmodels_get_return_attribution) or residual returns at the recommended hedge depth (use riskmodels_get_residual_returns). Returns, from GET /ticker-returns, the daily return series (decimal, 0.01 = 1%) with each day's L3 market, sector and subsector hedge ratios and explained-risk shares; history is point-in-time. End-of-day data, refreshed after each US market close. Price: $0.02 per call plus $0.01 per year of history beyond the first.

Use when you need one US stock's latest risk numbers: hedge ratios to SPY and to its sector and subsector ETFs, explained-risk shares by layer, volatility, closing price and market cap. Not for a layer-by-layer decomposition or the ETF hedge of a dollar position (use riskmodels_decompose), several stocks at once (use riskmodels_compare) or daily history (use riskmodels_get_returns). Returns the latest row of GET /metrics/{ticker}, including the hedge_levels block with hedge ratios, explained risk and hedge ETFs at L1, L2 and L3. End-of-day data, refreshed after each US market close. Price: $0.005 per call.

Use when a book has short positions or more than 100 names, or when you want its beta-dollars and the ETF trades that neutralise it. Not for long-only books of up to 100 names given as weights (use riskmodels_analyze_portfolio). Returns, from POST /portfolio/exposure, beta-dollars by sector, the ETF trades that neutralise the book at L1, L2 and L3, systematic and residual dollar risk at hedge_level (default lstar: each name at its own recommended depth), coverage (positions not modelled, with reasons) and warnings. Positions are netted by security and not rescaled. End-of-day data, refreshed after each US market close. Price: $0.25 per call up to 25 modelled names, $1.00 above.

Use when you want the names in the universe that rank highest or lowest on one metric, with optional percentile, decile and sector filters. Not for one stock's rank (use riskmodels_get_rankings). Returns, from POST /rankings/screen, the ranked rows that pass the filters; metrics, cohorts and windows are the same as for one stock's rank. End-of-day data, refreshed after each US market close. Price: $0.25 per call.

Use when you need to resolve a name or fragment to an identifier: a stock ticker, an ETF ticker, a mutual fund's bw_fund_id or a 13F filer's bw_filer_id. Not for data about the match (use riskmodels_get_stock_snapshot, riskmodels_get_etf, riskmodels_get_fund or riskmodels_get_filer). Returns matches from GET /tickers (type stock), GET /data/etf/search (etf), GET /funds/search (fund: bw_fund_id, ticker, name, style box, asset class, total assets) or GET /13f/filers/search (filer: bw_filer_id). Registry refreshed end-of-day. Free.