# GET /api/mcp/data/batch/iv-rank

> What is the IV rank of every name on my watchlist, in one call?

Returns the same IV rank payload as the single endpoint for each symbol in tickers, keyed by symbol under results. A symbol the feed cannot price lands in errors with its reason and never fails the others. The call spends one rate-limit unit however many symbols it names; the monthly allowance is spent per symbol, exactly as if each were called alone. Built for watchlist screens and morning briefs that used to take one request per name.

- **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:** IV values are annualised percentage points, declared by iv_units on every symbol's payload. IV rank and percentile are 0 to 100.
- **Basis:** Per symbol, identical to /iv-rank/{ticker}: the 30-day constant-maturity implied vol ranked against its own lookback_days history; the percentile is the vendor's one-year figure.
- **MCP tools:** `get_iv_rank`
- **Background:** https://apexvol.com/learn/iv-rank-percentile

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `tickers` (required) | query |  | 1 to 25 symbols, comma-separated | The underlyings, upper case, duplicates dropped. A symbol with no listed options answers 404 for the whole call and names the symbol. |
| `lookback_days` | query | 252 | 20 to 1260 | Trading days of history the rank is measured against, applied to every symbol. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/batch/iv-rank?tickers=SPY,QQQ,IWM"
```

## 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": {
    "errors": {},
    "failed": 0,
    "note": "One rate-limit unit for the whole call; the monthly allowance is spent per symbol, exactly as if each were called alone.",
    "requested": 3,
    "results": {
      "IWM": {
        "current_iv": 17.09,
        "data_source": "iv_rank_1y",
        "historical_data_points": 252,
        "is_full_year": true,
        "iv30d": 16.07,
        "iv_basis": "vendor_ivrank_series",
        "iv_max_52w": 32.56,
        "iv_mean": 21.53,
        "iv_median": 21.33,
        "iv_min_52w": 16.56,
        "iv_percentile": 4.0,
        "iv_percentile_1m": 33.33,
        "iv_percentile_1y": 4,
        "iv_percentile_source": "cores_ivPctile1y",
        "iv_rank": 3.33,
        "iv_rank_1m": 28.23,
        "iv_rank_1y": 3.33,
        "iv_state": "VERY_LOW",
        "iv_std": 3.04,
        "iv_stdv_from_mean": -1.34,
        "iv_units": "percentage_points",
        "lookback_days": 252,
        "ticker": "IWM",
        "timestamp": "2026-09-08T14:36:41.134388"
      },
      "QQQ": {
        "current_iv": 17.79,
        "data_source": "iv_rank_1y",
        "historical_data_points": 252,
        "is_full_year": true,
        "iv30d": 16.76,
        "iv_basis": "vendor_ivrank_series",
        "iv_max_52w": 28.34,
        "iv_mean": 20.67,
        "iv_median": 20.29,
        "iv_min_52w": 15.36,
        "iv_percentile": 17.0,
        "iv_percentile_1m": 23.81,
        "iv_percentile_1y": 17,
        "iv_percentile_source": "cores_ivPctile1y",
        "iv_rank": 18.73,
        "iv_rank_1m": 19.52,
        "iv_rank_1y": 18.73,
        "iv_state": "VERY_LOW",
        "iv_std": 2.9,
        "iv_stdv_from_mean": -0.84,
        "iv_units": "percentage_points",
        "lookback_days": 252,
        "ticker": "QQQ",
        "timestamp": "2026-09-08T14:36:40.024882"
      },
      "SPY": {
        "current_iv": 12.2,
        "data_source": "iv_rank_1y",
        "historical_data_points": 252,
        "is_full_year": true,
        "iv30d": 11.54,
        "iv_basis": "vendor_ivrank_series",
        "iv_max_52w": 24.98,
        "iv_mean": 14.7,
        "iv_median": 14.13,
        "iv_min_52w": 11.25,
        "iv_percentile": 6.0,
        "iv_percentile_1m": 14.29,
        "iv_percentile_1y": 6,
        "iv_percentile_source": "cores_ivPctile1y",
        "iv_rank": 6.86,
        "iv_rank_1m": 18.46,
        "iv_rank_1y": 6.86,
        "iv_state": "VERY_LOW",
        "iv_std": 2.42,
        "iv_stdv_from_mean": -0.78,
        "iv_units": "percentage_points",
        "lookback_days": 252,
        "ticker": "SPY",
        "timestamp": "2026-09-08T14:36:39.102977"
      }
    },
    "succeeded": 3,
    "tickers": [
      "SPY",
      "QQQ",
      "IWM"
    ]
  }
}
```

## Fields

- `tickers, requested, succeeded, failed`: The symbols asked for and how many answered.
- `results.{SYMBOL}`: The single-endpoint payload for that symbol: iv_rank, iv_percentile, current_iv, iv_max_52w, iv_min_52w, iv_units.
- `errors.{SYMBOL}`: Why a symbol is missing from results, in plain words.
- `note`: Reminds a client how the call is metered.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `403`: Premium plan required
- `424`: no symbol in the batch returned data
- `404`: a symbol with no listed options; the whole call fails and the body names it
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- What is the IV rank of SPY, QQQ and IWM right now?
- Rank my watchlist by IV rank, highest first.
- Which of AAPL, MSFT, NVDA and AMD has the cheapest implied vol for the year?

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