# GET /api/mcp/data/vrp/{ticker}/timeseries

> How has the gap between NVDA's implied and realized vol moved over the last few months?

One row per trading day with the 30-day IV, the realized vol over hv_period and the premium, plus a current block, so the premium can be charted or fed to a model.

- **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 values are annualised percentage points (iv_units).
- **Basis:** Same bases as /vrp: iv_basis and hv_basis are returned with the series.
- **MCP tools:** `get_volatility_risk_premium`
- **Background:** https://apexvol.com/learn/volatility-risk-premium

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `lookback_days` | query | 60 | 10 to 504 | How many trading days of history. |
| `hv_period` | query | 30 | 5 to 252 | Realized-vol window per point. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/vrp/NVDA/timeseries?lookback_days=60"
```

## 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": {
    "as_of": "2026-09-08T08:07:00.490425",
    "current": {
      "hv": 45.06,
      "hv_period": 30,
      "iv": 33.05,
      "vrp": -12.01
    },
    "hv_basis": "close_to_close_log_returns_annualized_252",
    "iv_basis": "iv30d_constant_maturity_eod",
    "iv_units": "percentage_points",
    "ticker": "NVDA",
    "timeseries": [
      {
        "date": "2026-07-24",
        "hv": 36.17,
        "iv": 40.05,
        "vrp": 3.88
      },
      {
        "date": "2026-07-27",
        "hv": 38.63,
        "iv": 44.02,
        "vrp": 5.39
      },
      {
        "date": "2026-07-28",
        "hv": 38.64,
        "iv": 44.53,
        "vrp": 5.89
      }
    ]
  }
}
```

## Fields

- `timeseries[].date, iv, hv, vrp`: The daily series.
- `current`: Today's iv, hv, vrp and the hv_period used.
- `as_of`: Last date in the series.

## 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

- Chart NVDA's volatility risk premium over the last 3 months.
- Has AAPL's IV been above realized for most of the year?
- Give me the IV versus HV series for TSLA as a table.

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