# GET /api/mcp/data/iv-rank/{ticker}

> Is NVDA's implied volatility high or low for NVDA right now?

Returns where today's implied volatility sits inside its own 52-week range (iv_rank, 0 to 100) and the share of days that closed with lower IV (iv_percentile), plus the min, max, mean and state label the numbers were built from.

- **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:** current_iv, iv30d and the range bounds are annualised IV in percentage points (34.43 means 34.43%). iv_rank and the percentiles are 0 to 100.
- **Basis:** iv_basis names the daily series the rank is measured on; iv30d is the 30-day constant-maturity IV used by the VRP endpoints, so the two can differ slightly. iv_percentile is the one-year percentile from the data feed.
- **MCP tools:** `get_iv_rank`
- **Background:** https://apexvol.com/learn/iv-rank-percentile

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `lookback_days` | query | 252 | 20 to 1260, clamped | Days of history behind the rank and the 1y percentile. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/iv-rank/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": {
    "current_iv": 34.43,
    "data_source": "iv_rank_1y",
    "historical_data_points": 252,
    "is_full_year": true,
    "iv30d": 33.05,
    "iv_basis": "vendor_ivrank_series",
    "iv_max_52w": 48.38,
    "iv_mean": 38.53,
    "iv_median": 38.39,
    "iv_min_52w": 32.01,
    "iv_percentile": 12.0,
    "iv_percentile_1m": 66.67,
    "iv_percentile_1y": 12,
    "iv_percentile_source": "cores_ivPctile1y",
    "iv_rank": 14.79,
    "iv_rank_1m": 54.08,
    "iv_rank_1y": 14.79,
    "iv_state": "VERY_LOW",
    "iv_std": 3.31,
    "iv_stdv_from_mean": -1.49,
    "iv_units": "percentage_points",
    "lookback_days": 252,
    "ticker": "NVDA",
    "timestamp": "2026-09-08T05:06:35.749922"
  }
}
```

## Fields

- `iv_rank`: Today's IV as a position between the 52-week low (0) and high (100).
- `iv_percentile`: Share of lookback days that closed with IV below today's.
- `current_iv`: The IV the rank was computed from, in percentage points.
- `iv30d`: The 30-day constant-maturity IV, the basis the VRP endpoints use.
- `iv_min_52w, iv_max_52w, iv_mean, iv_std`: The range and distribution behind the rank.
- `iv_state`: VERY_LOW to VERY_HIGH so a caller can branch without picking thresholds.
- `iv_rank_1m, iv_percentile_1m`: The same measures over the last month.

## 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 IV rank and percentile right now?
- Is implied volatility on AAPL high or low compared with the last year?
- Rank SPY, QQQ and IWM by IV rank.

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