# Tail Correlation API > Measures the thing that destroys portfolios: correlations that look comfortably low in calm markets but spike toward 1 exactly when the market crashes, so the diversifiers you were counting on all fall together — computed live from Yahoo Finance daily closes, no key, nothing stored. A normal full-sample correlation hides this by averaging the calm days with the crisis days; this API instead conditions on the benchmark's extremes. For each asset it returns the ordinary correlation to the benchmark, the crash correlation (measured only on the benchmark's worst days — its lower tail), the rally correlation (on its best days), and the breakdown: how much the correlation rises in a crash versus normal. A bond, gold or commodity position with a low normal correlation but a high crash correlation is a false diversifier; one whose correlation stays low or falls in the tail is a genuine hedge. The asset endpoint returns one instrument's full tail-correlation profile; the screener endpoint ranks the cross-asset universe by crash correlation, surfacing which holdings actually fail when you need them. This is the conditional / tail-correlation cut — distinct from the unconditional cross-asset, sector and FX correlation matrices (which average all days together), the up/down capture API (magnitudes, not co-movement) and the price APIs. It is correlation when it matters: in the crash. ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/tailcorr-api/..." ``` ## Pricing - **Free** (Free) — 675 calls/Mo, 2 req/s - **Starter** ($13/Mo) — 15,100 calls/Mo, 6 req/s - **Pro** ($37/Mo) — 84,500 calls/Mo, 16 req/s - **Mega** ($81/Mo) — 472,000 calls/Mo, 40 req/s ## Endpoints ### Screener #### `GET /v1/screener` — Rank the universe by crash correlation + diversification breakdown **Parameters:** - `benchmark` (query, optional, string) — Universe symbol used as benchmark Example: `SPY` - `tail` (query, optional, string) — Extreme-day percentile (5-25) Example: `10` - `window` (query, optional, string) — Lookback in trading days (90-756) Example: `252` - `class` (query, optional, string) — equity, sector, commodity, bond, fx, crypto or all Example: `all` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tailcorr-api/v1/screener?benchmark=SPY&tail=10&window=252&class=all" ``` **Response:** ```json { "data": { "note": "Computed vs SPY over window_days. normal_correlation uses all days; crash_correlation only the benchmark's worst 10% of days (its lower tail); rally_correlation only its best 10%. breakdown = crash - normal: positive means the asset correlates MORE in a crash (a false diversifier); a low or negative crash_correlation is a genuine crisis hedge. Read fresh per call, nothing cached.", "class": "all", "count": 20, "source": "Yahoo Finance", "results": [ { "name": "S&P 500", "rank": 1, "class": "equity", "symbol": "SPY", "tail_pct": 10, "available": true, "breakdown": 0, "crash_days": 26, "rally_days": 26, "observations": 252, "crash_correlation": 1, "rally_correlation": 1, "normal_correlation": 1 }, { "name": "Nasdaq 100", "rank": 2, "class": "equity", "symbol": "QQQ", "tail_pct": 10, "available": true, "breakdown": -0.077, "crash_days": 26, "rally_days": 26, "observations": 252, "crash_correlation": 0.864, "rally_correlation": 0.841, "normal_correlation": 0.942 …(truncated, see openapi.json for full schema) ``` ### Asset #### `GET /v1/asset` — Full tail-correlation profile of one instrument **Parameters:** - `symbol` (query, required, string) — Universe symbol Example: `HYG` - `benchmark` (query, optional, string) — Benchmark symbol Example: `SPY` - `tail` (query, optional, string) — Extreme-day percentile (5-25) Example: `10` - `window` (query, optional, string) — Lookback in trading days (90-756) Example: `252` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tailcorr-api/v1/asset?symbol=HYG&benchmark=SPY&tail=10&window=252" ``` **Response:** ```json { "data": { "name": "High-Yield Credit", "note": "normal_correlation over all days vs crash_correlation on the benchmark's worst 10% of days and rally_correlation on its best. breakdown = crash - normal. A false diversifier has low normal but high crash correlation. Read fresh per call, nothing cached.", "class": "bond", "reads": { "crash": "partial diversification in a crash", "breakdown": "correlation is stable across regimes" }, "source": "Yahoo Finance", "symbol": "HYG", "tail_pct": 10, "benchmark": "SPY", "breakdown": -0.19, "crash_days": 26, "rally_days": 26, "window_days": 252, "observations": 252, "benchmark_name": "S&P 500", "crash_correlation": 0.518, "rally_correlation": 0.632, "normal_correlation": 0.708 }, "meta": { "timestamp": "2026-06-12T10:34:44.986Z", "request_id": "f5bdc3e4-19b7-4110-ba47-bd48be7c19b0" }, "status": "ok", "message": "Asset tail correlation retrieved successfully", "success": true } ``` ### Universe #### `GET /v1/universe` — The cross-asset universe and its classes **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tailcorr-api/v1/universe" ``` **Response:** ```json { "data": { "note": "The cross-asset universe the screener ranks. Pass class= to a screener call to rank within one class.", "count": 20, "assets": [ { "name": "S&P 500", "class": "equity", "symbol": "SPY" }, { "name": "Nasdaq 100", "class": "equity", "symbol": "QQQ" }, { "name": "US Small Caps", "class": "equity", "symbol": "IWM" }, { "name": "Developed ex-US", "class": "equity", "symbol": "EFA" }, { "name": "Emerging Markets", "class": "equity", "symbol": "EEM" }, { "name": "Technology", "class": "sector", "symbol": "XLK" }, { "name": "Financials", "class": "sector", "symbol": "XLF" }, { "name": "Energy", "class": "sector", "symbol": "XLE" }, { "name": "Health Care", "class": "sector", "symbol": "XLV" }, { "name": "Utilities", "class": "sector", "symbo …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Service metadata **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/tailcorr-api/v1/meta" ``` **Response:** ```json { "data": { "note": "benchmark is any universe symbol (default SPY). window is 90-756 trading days (default 252). tail is the extreme-day percentile, 5-25 (default 10). class filters to equity/sector/commodity/bond/fx/crypto (default all). Correlations are Pearson on daily returns. Read fresh per call, nothing cached.", "source": "Yahoo Finance daily closes, live", "classes": [ "equity", "sector", "commodity", "bond", "fx", "crypto" ], "service": "tailcorr-api", "endpoints": { "GET /v1/meta": "This document.", "GET /v1/asset": "Full tail-correlation profile of one instrument (symbol=HYG, benchmark=SPY, tail=10, window=252).", "GET /v1/screener": "Rank the universe by crash correlation, with the diversification breakdown (benchmark=SPY, tail=10, window=252, class=all).", "GET /v1/universe": "The cross-asset universe and its classes." }, "description": "Tail correlation / diversification breakdown — correlations that look low in calm markets but spike toward 1 when the market crashes, live from Yahoo Finance daily closes (no key, nothing stored). For each asset it returns the ordinary correlation to the benchmark, the crash correlation (only the benchmark's worst days), the rally correlation (its best days) and the breakdown (crash minus normal). A low normal but high crash correlation marks …(truncated, see openapi.json for full schema) ``` --- Marketplace page: https://www.oanor.com/api/tailcorr-api OpenAPI spec: https://www.oanor.com/api/tailcorr-api/openapi.json