# GET /api/mcp/data/screen

> Which stocks have the highest IV rank right now?

Runs one of the preset screens over the covered universe in one or two bulk calls and returns the matching rows with price, IV, realized vol, VRP, skew percentile, earnings timing and market cap. screen_type=list returns the catalog.

- **Family:** Screeners (https://apexvol.com/developers/screeners-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:** iv30d, iv60d, hv20d in percentage points; vrp in points; chg_1w and chg_1m in percent; market_cap in dollars.
- **Basis:** Daily bulk data from the feed; iv_percentile is the one-year figure.
- **MCP tools:** `screen_market`
- **Background:** https://apexvol.com/learn/options-screener-guide

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `screen_type` | query | high_iv_rank | high_iv_rank, low_iv_rank, high_vrp, earnings_this_week, high_skew, steep_contango, mean_reversion, vol_pairs, decorrelation, unusual_volume, pin_risk, list | Which preset. |
| `limit` | query | 20 | 1 to 200 | Rows. |
| `min_market_cap` | query | 1000000000 | dollars | Floor on size. |
| `exclude_earnings_days` | query | 0 | 0 to 60 | Drop names reporting within N days. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/screen?screen_type=high_iv_rank&limit=5"
```

## 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": {
    "results": [
      {
        "asset_type": "Stock",
        "avg_opt_volume": 181.0,
        "beta": 0.64,
        "chg_1m": 11.05,
        "chg_1w": 14.47,
        "contango": -30.8,
        "days_to_earnings": 57,
        "hv20d": 34.5,
        "imp_earn_move": 16.18,
        "iv30d": 243.0,
        "iv60d": 177.2,
        "iv_percentile": 100,
        "market_cap": "$1.7B",
        "market_cap_raw": 1703777000.0,
        "next_earnings": "2026-11-04",
        "price": 24.86,
        "sector": "Healthcare",
        "skew_pctile": 78.0,
        "stock_volume": 44616,
        "ticker": "TYRA",
        "vrp": null
      },
      {
        "asset_type": "Stock",
        "avg_opt_volume": 76.0,
        "beta": 1.34,
        "chg_1m": 7.87,
        "chg_1w": -6.13,
        "contango": 5.76,
        "days_to_earnings": 58,
        "hv20d": 36.3,
        "imp_earn_move": 15.12,
        "iv30d": 113.4,
        "iv60d": 115.7,
        "iv_percentile": 100,
        "market_cap": "$2.2B",
        "market_cap_raw": 2196446000.0,
        "next_earnings": "2026-11-05",
        "price": 47.65,
        "sector": "Healthcare",
        "skew_pctile": 46.0,
        "stock_volume": 6826,
        "ticker": "RAPP",
        "vrp": 77.1
      },
      {
        "asset_type": "ETF",
        "avg_opt_volume": 14.0,
        "beta": 0.61,
        "chg_1m": 7.91,
        "chg_1w": 1.71,
        "contango": -1.08,
        "days_to_earnings": null,
        "hv20d": 13.7,
        "imp_earn_move": 0.0,
        "iv30d": 25.0,
        "iv60d": 25.0,
        "iv_percentile": 100,
        "market_cap": "$5.2B",
        "market_cap_raw": 5212689000.0,
        "next_earnings": null,
        "price": 79.29,
        "sector": "Materials",
        "skew_pctile": 57.0,
        "stock_volume": 7381,
        "ticker": "GNR",
        "vrp": 11.4
      }
    ],
    "scan_time": "2026-09-08T07:50:11",
    "screen_description": "Tickers with elevated IV: selling premium opportunities",
    "screen_name": "High IV Rank",
    "screen_type": "high_iv_rank",
    "total_results": 298,
    "total_scanned": 5963,
    "universe_size": 2318
  }
}
```

## Fields

- `results[].ticker, price, iv30d, hv20d, vrp, iv_percentile`: The row.
- `results[].skew_pctile, contango, days_to_earnings, imp_earn_move`: Extra columns per screen.
- `screen_name, screen_description, total_scanned, universe_size`: What ran.

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

- Screen for the highest IV rank stocks over 5 billion market cap.
- Which names have the richest premium over realized this week?
- List the available screens.

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