Risk Metrics

Daily returns time series with rolling hedge ratios (stocks and ETFs)

Returns a daily time series of gross returns (returns_gross) and, for stocks, V3 rolling hedge ratios and explained-risk fields per day: l3_mkt_hr, l3_sec_hr, l3_sub_hr, l3_mkt_er, l3_sec_er, l3_sub_er, l3_res_er. Up to 15 years per request. ETFs are supported: requests for ETF tickers (e.g. SPY, XLK) return date, returns_gross, and price_close sourced from ds_etf.zarr; L1/L2/L3 columns are null because ETFs are not factor-decomposed. The response includes asset_type ("stock" or "etf") so clients can branch cleanly. For the full L1/L2/L3 snapshot (all six HR names on the latest day), use GET /metrics/{ticker} (metrics object). Response does not include a top-level _agent block; billing is applied server-side. Cost: $0.02 for 1 year + $0.01 per extra year (up to 15). A response with no rows is not billed; _metadata.data_warning_code names the reason (etf_outside_priced_universe, etf_no_return_history_in_window or no_return_history_in_window). Only ETFs with the priced capability return rows — see GET /data/etf/universe.

get/ticker-returns

Request

  • Base URL: https://riskmodels.app/api
  • URL: https://riskmodels.app/api/ticker-returns
  • Auth: HTTP bearer

Query parameters

tickerstring required
yearsinteger

Number of years of history to return.

limitinteger

Maximum number of rows to return.

nocacheboolean

Bypass cache (incurs cost even if identical request was recently made).

format'json' | 'parquet' | 'csv'

Response carrier. json (default): structured payload for this operation (body includes _metadata where documented). parquet / csv: a single flat table of time-series rows only — lineage comes from X-Risk-Model-Version, X-Data-As-Of, X-Factor-Set-Id, X-Universe-Size. When this parameter is omitted, Accept: application/vnd.apache.parquet or Accept: text/csv selects the tabular format.

Response

Time series of daily returns, price_close, and V3 rolling HR/ER fields. JSON wraps rows in data with symbol, ticker, meta, _metadata. Parquet/CSV are a single table: one row per trading day; columns match #/components/schemas/TickerReturnsDailyRow in a stable key order (same field names as JSON object keys in each data element).

symbolstring required
tickerstring required
asset_type'stock' | 'etf'

Returned for every response. ETF responses populate date, returns_gross, and price_close only; all L1/L2/L3 columns are null because ETFs are not factor-decomposed.

resolved_via'most_recent_holder'

Present only when the modelled registry has no live row for the requested ticker and the most-recent-holder check chose the answer: the security that holds the ticker today (it may have a registry row under another ticker, then disclosed in modelled_ticker) or, failing that, the one that held it most recently (e.g. the delisted CTRA). Tickers with a live registry row, including recycled ones, resolve to today's company and omit this field, as do answers unchanged from earlier releases (an alias rename such as FB → META, or a delisted registry row) unless a live holder of the ticker that the API can serve exists.

modelled_tickerstring nullable

With resolved_via: the answering security's own ticker (registry or security master) when it differs from the requested ticker, e.g. BYON for a BBBY request answered by a listing pin.

delistedboolean

true when the answering security is closed in the security master or flagged delisted in the registry; false when the most-recent-holder pass found it open. Absent on ordinary answers and on answers kept unchanged from earlier releases whose registry row is not flagged delisted.

ticker_reassignedboolean

true when the security master shows a different security holding the ticker today that the API cannot serve (no registry row under the ticker, no daily history), so the answer is still the previous holder's series (e.g. FB keeps answering Meta while another security holds FB). Absent otherwise.

resolution_degradedboolean

true when the most-recent-holder check could not read its evidence (security master, registry or daily index outage) and the previous answer was returned unchecked; a later request may answer a different security. Absent otherwise.

periodicitystring required

Example response

{
  "_metadata": {
    "see": "/api/data/etf/HYG"
  },
  "periodicity": "daily",
  "meta": {
    "market_etf": "SPY",
    "sector_etf": "SOXX",
    "subsector_etf": "XSD",
    "universe": "US_EQUITY"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.