# GET /api/mcp/data/flow/{ticker}

> What are the largest NVDA option trades today, and are they bullish or bearish?

Returns the largest flows, the unusual activity (volume far above open interest), the full flow list, the most active strikes and expirations, and a summary with net premium and a sentiment label. Compact detail caps the row lists.

- **Family:** Options flow (https://apexvol.com/developers/options-flow-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:** premium in dollars; volume and oi in contracts; volume_oi_ratio unitless.
- **Basis:** Aggregated from today's cumulative volume by contract; is_market_hours and data_freshness say how live the data is.
- **MCP tools:** `get_options_flow`
- **Background:** https://apexvol.com/learn/open-interest-volume

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `detail` | query | full for REST, compact for MCP clients | compact or full | Capped lists or everything. |
| `limit` | query | 25 | rows in all_flow under compact | Row cap. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/flow/NVDA?detail=compact&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": {
    "all_flow": [
      {
        "ask": 10.15,
        "bid": 10.05,
        "delta": -0.4599,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 10.100000000000001,
        "moneyness": "OTM",
        "oi": 6669,
        "premium": 11948300.000000002,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.681049",
        "type": "PUT",
        "volume": 11830,
        "volume_oi_ratio": 1.773879142300195
      },
      {
        "ask": 4.0,
        "bid": 3.95,
        "delta": 0.5173,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": false,
        "mid": 3.975,
        "moneyness": "ITM",
        "oi": 32787,
        "premium": 10783380.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542239",
        "type": "CALL",
        "volume": 27128,
        "volume_oi_ratio": 0.8274011040961357
      },
      {
        "ask": 6.05,
        "bid": 5.95,
        "delta": 0.5225,
        "dte": 10,
        "expiration": "2026-09-18",
        "is_unusual": false,
        "mid": 6.0,
        "moneyness": "ITM",
        "oi": 57448,
        "premium": 10345800.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.600692",
        "type": "CALL",
        "volume": 17243,
        "volume_oi_ratio": 0.3001497005988024
      }
    ],
    "data_freshness": "EOD",
    "is_market_hours": false,
    "largest_flows": [
      {
        "ask": 10.15,
        "bid": 10.05,
        "delta": -0.4599,
        "dte": 38,
        "expiration": "2026-10-16",
        "is_unusual": false,
        "mid": 10.1,
        "moneyness": "OTM",
        "oi": 6669,
        "premium": 11948300.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.681049",
        "type": "PUT",
        "volume": 11830,
        "volume_oi_ratio": 1.7739
      },
      {
        "ask": 4.0,
        "bid": 3.95,
        "delta": 0.5173,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": false,
        "mid": 3.975,
        "moneyness": "ITM",
        "oi": 32787,
        "premium": 10783380.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542239",
        "type": "CALL",
        "volume": 27128,
        "volume_oi_ratio": 0.8274
      },
      {
        "ask": 6.05,
        "bid": 5.95,
        "delta": 0.5225,
        "dte": 10,
        "expiration": "2026-09-18",
        "is_unusual": false,
        "mid": 6.0,
        "moneyness": "ITM",
        "oi": 57448,
        "premium": 10345800.0,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.600692",
        "type": "CALL",
        "volume": 17243,
        "volume_oi_ratio": 0.3001
      }
    ],
    "message": "Market is closed. Showing end-of-day data from the most recent trading session.",
    "stock_price": 230.3,
    "success": true,
    "summary": {
      "call_put_ratio": 1.9932,
      "net_premium": 172969531.5,
      "put_call_ratio": 0.5017,
      "sentiment": "BULLISH",
      "total_call_premium": 317997531.0,
      "total_call_volume": 1172710.0,
      "total_flow_count": 342,
      "total_put_premium": 145027999.5,
      "total_put_volume": 588346.0
    },
    "ticker": "NVDA",
    "timestamp": "2026-09-08T08:07:24.702149",
    "top_expirations": [
      [
        "2026-09-18",
        {
          "premium": 100034602.0,
          "volume": 283452
        }
      ],
      [
        "2026-09-11",
        {
          "premium": 98571641.0,
          "volume": 539458
        }
      ],
      [
        "2026-10-16",
        {
          "premium": 87886168.0,
          "volume": 170080
        }
      ]
    ],
    "top_strikes": [
      [
        230.0,
        {
          "calls": 100849,
          "premium": 91238806.0,
          "puts": 87969,
          "volume": 188818
        }
      ],
      [
        235.0,
        {
          "calls": 194678,
          "premium": 76153200.5,
          "puts": 30408,
          "volume": 225086
        }
      ],
      [
        232.5,
        {
          "calls": 101063,
          "premium": 42516519.0,
          "puts": 37409,
          "volume": 138472
        }
      ]
    ],
    "unusual_activity": [
      {
        "ask": 2.65,
        "bid": 2.58,
        "delta": -0.4734,
        "dte": 1,
        "expiration": "2026-09-09",
        "is_unusual": true,
        "mid": 2.615,
        "moneyness": "OTM",
        "oi": 1454,
        "premium": 9326397.5,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.518008",
        "type": "PUT",
        "volume": 35665,
        "volume_oi_ratio": 24.5289
      },
      {
        "ask": 3.8,
        "bid": 3.75,
        "delta": -0.4827,
        "dte": 3,
        "expiration": "2026-09-11",
        "is_unusual": true,
        "mid": 3.775,
        "moneyness": "OTM",
        "oi": 2231,
        "premium": 8328782.5,
        "strike": 230.0,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.542254",
        "type": "PUT",
        "volume": 22063,
        "volume_oi_ratio": 9.8893
      },
      {
        "ask": 4.0,
        "bid": 3.9,
        "delta": -0.6144,
        "dte": 1,
        "expiration": "2026-09-09",
        "is_unusual": true,
        "mid": 3.95,
        "moneyness": "ITM",
        "oi": 226,
        "premium": 9502515.0,
        "strike": 232.5,
        "ticker": "NVDA",
        "timestamp": "2026-09-08T08:07:24.518071",
        "type": "PUT",
        "volume": 24057,
        "volume_oi_ratio": 106.4469
      }
    ],
    "window": {
      "detail": "compact",
      "limit": 5,
      "lists": {
        "all_flow": {
          "rows_returned": 5,
          "rows_total": 100,
          "truncated": true
        },
        "largest_flows": {
          "rows_returned": 5,
          "rows_total": 20,
          "truncated": true
        },
        "unusual_activity": {
          "rows_returned": 5,
          "rows_total": 20,
          "truncated": true
        }
      }
    }
  }
}
```

## Fields

- `summary.sentiment, net_premium, call_put_ratio`: The read in three numbers.
- `largest_flows[].strike, expiration, type, premium, volume, oi`: The biggest tickets.
- `unusual_activity[]`: Contracts where volume dwarfs open interest.
- `top_strikes, top_expirations`: Where the activity clusters.
- `window`: What compact detail trimmed.

## 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 the options flow on NVDA today, bullish or bearish?
- Show unusual options activity on AAPL.
- What are the largest premium trades on SPY this session?

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