# GET /api/mcp/data/market-overview

> What is the volatility regime across the market today?

One call with the average IV and VRP across the universe, the regime label, a sector heatmap, ETF heatmap, index levels, rates, put skew, vol breadth, top movers, unusual activity and the IV-versus-HV outliers.

- **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:** IVs in percentage points; VRP in points; changes in percent; yields in percent; OI and volume in contracts.
- **Basis:** Bulk daily data across the covered universe.
- **MCP tools:** `get_market_overview`
- **Background:** https://apexvol.com/learn/volatility-trading

## Parameters

No parameters.

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/market-overview"
```

## 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": {
    "earnings_this_week": [
      {
        "capGroup": "large",
        "days_to_earnings": 0,
        "hv20d": 34.0,
        "iv30d": 48.3,
        "iv_percentile": 98.0,
        "market_cap": "$28.0B",
        "next_earnings": "2026-09-08",
        "price": 755.96,
        "sector": "C. Defensive",
        "ticker": "CASY",
        "vrp": 14.2
      },
      {
        "capGroup": "mid",
        "days_to_earnings": 0,
        "hv20d": 22.4,
        "iv30d": 52.2,
        "iv_percentile": 52.0,
        "market_cap": "$8.6B",
        "next_earnings": "2026-09-08",
        "price": 19.19,
        "sector": "C. Cyclical",
        "ticker": "GME",
        "vrp": 29.8
      },
      {
        "capGroup": "mid",
        "days_to_earnings": 0,
        "hv20d": 28.9,
        "iv30d": 67.6,
        "iv_percentile": 71.0,
        "market_cap": "$2.7B",
        "next_earnings": "2026-09-08",
        "price": 43.87,
        "sector": "C. Defensive",
        "ticker": "UNFI",
        "vrp": 38.8
      }
    ],
    "index_prices": {
      "DJX": {
        "chg1m": -1.87,
        "chg1w": -0.43,
        "chg_today": 0,
        "iv30d": 11.2,
        "name": "Dow Jones",
        "price": 53686.0
      },
      "NDX": {
        "chg1m": -0.01,
        "chg1w": 0.17,
        "chg_today": 0,
        "iv30d": 16.4,
        "name": "Nasdaq 100",
        "price": 29482.32
      },
      "SPX": {
        "chg1m": -0.08,
        "chg1w": 0.07,
        "chg_today": 0,
        "iv30d": 11.2,
        "name": "S&P 500",
        "price": 7747.71
      },
      "VIX": {
        "chg1m": -8.67,
        "chg1w": 0.07,
        "chg_today": 0,
        "iv30d": 77.8,
        "name": "VIX",
        "price": 14.32
      }
    },
    "market_stats": {
      "avg_contango": -0.06,
      "avg_iv30d": 45.8,
      "avg_iv_percentile": 36.1,
      "avg_put_call_ratio": 0.67,
      "avg_vrp": 6.3,
      "market_regime": "Normal",
      "median_iv_percentile": 33.0,
      "pct_high_iv": 12.4,
      "regime_color": "green",
      "total_options_oi": 583148513,
      "total_options_vol": 76063634,
      "total_tickers": 4011
    },
    "put_skew": {
      "avg_skew_pctile": 39.4,
      "avg_slope": 0.85,
      "avg_slope_1y": 1.37
    },
    "scan_time": "2026-09-08T05:01:41",
    "sector_heatmap": [
      {
        "avg_contango": -0.21,
        "avg_iv30d": 39.6,
        "avg_iv_percentile": 45.1,
        "avg_vrp": 3.8,
        "sector": "C. Defensive",
        "ticker_count": 118
      },
      {
        "avg_contango": -0.32,
        "avg_iv30d": 29.6,
        "avg_iv_percentile": 42.6,
        "avg_vrp": 4.1,
        "sector": "Utilities",
        "ticker_count": 86
      },
      {
        "avg_contango": 0.32,
        "avg_iv30d": 60.5,
        "avg_iv_percentile": 40.0,
        "avg_vrp": 3.5,
        "sector": "Technology",
        "ticker_count": 422
      }
    ],
    "top_movers": [
      {
        "capGroup": "mega",
        "iv30d": 33.2,
        "iv_percentile": 100.0,
        "market_cap": "$237.5B",
        "price": 439.35,
        "sector": "Healthcare",
        "ticker": "AMGN",
        "vrp": 12.0
      },
      {
        "capGroup": "small",
        "iv30d": 22.0,
        "iv_percentile": 100.0,
        "market_cap": "$493M",
        "price": 50.91,
        "sector": "N/A",
        "ticker": "AMZA",
        "vrp": 2.7
      },
      {
        "capGroup": "mid",
        "iv30d": 143.5,
        "iv_percentile": 100.0,
        "market_cap": "$3.1B",
        "price": 39.55,
        "sector": "Healthcare",
        "ticker": "CLDX",
        "vrp": null
      }
    ],
    "treasury_rates": {
      "^FVX": {
        "chg_bps": 4.1,
        "name": "5-Year",
        "yield": 4.55
      },
      "^TNX": {
        "chg_bps": 2.2,
        "name": "10-Year",
        "yield": 4.784
      },
      "^TYX": {
        "chg_bps": 0.3,
        "name": "30-Year",
        "yield": 5.246
      }
    },
    "vol_breadth": {
      "pct_contango_positive": 60.6,
      "pct_iv_above_hv": 76.4,
      "pct_iv_pctile_above_50": 27.8
    }
  }
}
```

## Fields

- `market_stats.market_regime, avg_iv30d, avg_vrp, pct_high_iv`: The regime.
- `sector_heatmap[], etf_heatmap[]`: By sector and ETF.
- `index_prices, treasury_rates`: Levels and rates.
- `vol_breadth, put_skew`: Breadth and skew across names.
- `top_movers[], unusual_activity[], earnings_this_week[]`: The lists.

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

- Give me a market volatility overview for this morning.
- Which sectors have the highest IV right now?
- Is the market in a high-vol regime?

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