# GET /api/mcp/data/hv-regimes/{ticker}

> What realized-vol regime is NVDA in, and are the short windows above or below the long ones?

Returns close-to-close realized vol at 5 to 252 day windows as a time series, the HV term structure with the vendor's alternative estimator, and a forecast block. Other views return the signals, the decomposition, or an ex-earnings series.

- **Family:** Implied volatility (https://apexvol.com/developers/implied-volatility-api)
- **Plan:** Premium and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** All volatilities are annualised percentage points.
- **Basis:** cls_hv is close-to-close; or_hv is the data feed's intraday-range estimator. view=ex_earnings recomputes the 30-day tenor from daily closes with earnings reaction sessions dropped.
- **MCP tools:** `get_ticker_analytics`
- **Background:** https://apexvol.com/learn/volatility-trading

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `view` | query | dashboard | dashboard, signals, decomposition, ex_earnings | Which block to return. |
| `days` | query | 252 | 20 to 1000 | History length. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/hv-regimes/NVDA"
```

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "days": 252,
    "forecast": {
      "orFcst20d": null,
      "orFcstInf": null
    },
    "term_structure": [
      {
        "cls_hv": 24.54,
        "or_hv": 32.68,
        "window": "5d"
      },
      {
        "cls_hv": 56.32,
        "or_hv": 46.76,
        "window": "10d"
      },
      {
        "cls_hv": 44.38,
        "or_hv": 37.68,
        "window": "20d"
      }
    ],
    "ticker": "NVDA",
    "timeseries": [
      {
        "clsHv10d": 25.76,
        "clsHv120d": 46.85,
        "clsHv20d": 22.91,
        "clsHv252d": 50.25,
        "clsHv30d": 24.9,
        "clsHv5d": 23.98,
        "clsHv60d": 26.55,
        "clsHv90d": 29.17,
        "date": "2025-09-05"
      },
      {
        "clsHv10d": 24.09,
        "clsHv120d": 46.76,
        "clsHv20d": 22.7,
        "clsHv252d": 50.21,
        "clsHv30d": 25.03,
        "clsHv5d": 22.25,
        "clsHv60d": 26.48,
        "clsHv90d": 29.17,
        "date": "2025-09-08"
      },
      {
        "clsHv10d": 24.88,
        "clsHv120d": 46.47,
        "clsHv20d": 23.59,
        "clsHv252d": 50.22,
        "clsHv30d": 24.79,
        "clsHv5d": 22.9,
        "clsHv60d": 26.47,
        "clsHv90d": 29.19,
        "date": "2025-09-09"
      }
    ]
  }
}
```

## Fields

- `timeseries[].clsHv5d to clsHv252d`: Realized vol per window per day.
- `term_structure[].window, cls_hv, or_hv`: The HV term structure.
- `forecast`: Vendor forecast of 20-day and long-run vol when available.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `403`: Premium plan required
- `424`: data feed unavailable, retry
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- What is NVDA's 20-day realized vol versus its 1-year?
- Show the realized-vol term structure for AAPL.
- Give me TSLA's realized vol excluding earnings days.

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions