> ## Documentation Index
> Fetch the complete documentation index at: https://api.unusualwhales.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# Flow alerts

> Receive live flow alerts (all of them unfiltered).

**NOTE:**
This is the documentation for websocket channel `flow-alerts`.
Websocket access for personal use is only available through the [Advanced plan](https://unusualwhales.com/pricing?product=api).

You can find fully-functional examples that stream data from many channels here:

* Python: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output)
* Javascript: [https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs](https://github.com/unusual-whales/api-examples/tree/main/examples/ws-multi-channel-multi-output-nodejs)

Connect to the websocket URI:

`wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN>`

then `join` the channel you wish to stream: `flow-alerts` for all flow alerts.

Payload format:

```
[
  "flow-alerts",
  {
    "rule_id": "5ce5ec11-087c-4c00-b164-08106b015856",
    "rule_name": "RepeatedHitsDescendingFill",
    "ticker": "DIA",
    "option_chain": "DIA241018C00415000",
    "underlying_price": 415.981,
    "volume": 106,
    "total_size": 50,
    "total_premium": 36466,
    "total_ask_side_prem": 36466,
    "total_bid_side_prem": 0,
    "start_time": 1726670212648,
    "end_time": 1726670212748,
    "url": "",
    "price": 7.3,
    "has_multileg": false,
    "has_sweep": false,
    "has_floor": false,
    "open_interest": 575,
    "all_opening_trades": false,
    "id": "29ed5829-e4ce-4934-876b-51985d2f9b70",
    "has_singleleg": true,
    "volume_oi_ratio": 0,
    "trade_ids": [
      "417f0cd6-09ae-4d43-8542-38557bb713aa",
      "4af4c646-4b21-4a27-8326-db7b0698d3d8",
      "74ddcd55-dcb3-4543-a488-16ee7ca91d45",
      "4ec49859-74a2-4d32-9911-ea329dd77326",
      "e164da3a-a6aa-41d9-a948-c17817453a21",
      "b0d98eeb-1429-4494-9dcc-8d5e7eb46f7d",
      "81b1dcad-f3f6-48a2-bf51-0bfd362ad372"
    ],
    "trade_count": 7,
    "expiry_count": 1,
    "executed_at": 1726670212748,
    "ask_vol": 52,
    "bid_vol": 49,
    "no_side_vol": 0,
    "mid_vol": 5,
    "multi_vol": 0,
    "stock_multi_vol": 0,
    "upstream_condition_details": [
      "auto",
      "slan"
    ],
    "exchanges": [
      "XCBO",
      "MPRL"
    ],
    "bid": "7.15",
    "ask": "7.3",
    "iv": 0.2543,
    "delta": 0.4821,
    "gamma": 0.0125,
    "theta": -0.0342,
    "vega": 0.1187,
    "rho": 0.0456,
    "theo": 7.28
  }
]
```

### Field reference

A flow alert is an aggregate of one or more individual `option_trades` that matched a rule (sweep, repeated hits, etc.). Use `trade_ids` to look up the underlying option trades.

| Field | Type | Description |
| - | - | - |
| `id` | uuid string | Unique alert identifier. |
| `rule_id` | uuid string | Identifier of the rule that produced the alert. |
| `rule_name` | string \| null | Human-readable rule name (e.g. `"RepeatedHitsDescendingFill"`). May be null if the rule definition is not present. |
| `ticker` | string | Underlying ticker. |
| `option_chain` | string | OSI option chain id matched by the alert. |
| `underlying_price` | float | Spot price of the underlying at `end_time`. |
| `volume` | int | Aggregate session volume on the contract at `end_time`. |
| `total_size` | int | Sum of `size` across the trades in this alert. |
| `total_premium` | float | Sum of `premium` across the trades in this alert. |
| `total_ask_side_prem` / `total_bid_side_prem` | float | Premium broken out by side classification at trade time. |
| `start_time` / `end_time` | int (ms) | First and last trade timestamps included in the alert (unix epoch milliseconds). |
| `executed_at` | int (ms) | Same as `end_time` (kept for backwards compatibility). |
| `price` | float | Last trade price in the aggregation window. |
| `bid` / `ask` | decimal string | NBBO at `end_time`. |
| `open_interest` | int | Open interest on the contract as of the most recent close. |
| `volume_oi_ratio` | float | `volume / open_interest`. `0` if `open_interest` is `0`. |
| `has_sweep` / `has_floor` / `has_singleleg` / `has_multileg` | bool | True if at least one matching trade is of that kind. |
| `all_opening_trades` | bool | True if every matching trade looks like an opening trade (price near ask). |
| `trade_ids` | string\[] | UUIDs of the underlying `option_trades`; cross-reference against the `option_trades` channel or the full-tape endpoint. |
| `trade_count` | int | `length(trade_ids)`. |
| `expiry_count` | int | Number of distinct expiries spanned by the matching trades (almost always `1`). |
| `ask_vol` / `bid_vol` / `mid_vol` / `no_side_vol` | int | Aggregate volume by side classification across the trades. |
| `multi_vol` / `stock_multi_vol` | int | Multi-leg / stock-combo volume across the trades. |
| `upstream_condition_details` | string\[] | Union of upstream condition codes (`"slan"`, `"auto"`, ...) seen across the trades. |
| `exchanges` | string\[] | OPRA exchanges that printed the matching trades. |
| `url` | string | Deep link to the alert on unusualwhales.com (may be empty). |
| `iv` | float \| null | Size-weighted implied volatility across the trades in the alert. `null` when unavailable. |
| `delta` | float \| null | Size-weighted delta across the trades in the alert. `null` when unavailable. |
| `gamma` | float \| null | Size-weighted gamma across the trades in the alert. `null` when unavailable. |
| `theta` | float \| null | Size-weighted theta across the trades in the alert. `null` when unavailable. |
| `vega` | float \| null | Size-weighted vega across the trades in the alert. `null` when unavailable. |
| `rho` | float \| null | Size-weighted rho across the trades in the alert. `null` when unavailable. |
| `theo` | float \| null | Size-weighted theoretical option price across the trades in the alert. `null` when unavailable. |