# Flow alerts

`GET` `https://api.unusualwhales.com/api/socket/flow_alerts`

**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"
  }
]
```

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



## Authentication

```
Authorization: Bearer YOUR_API_KEY
```



## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/socket/flow_alerts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

### Python

```python
import http.client

conn = http.client.HTTPSConnection("api.unusualwhales.com")
headers = {"Authorization": "Bearer YOUR_API_KEY", "Accept": "application/json"}
conn.request("GET", "/api/socket/flow_alerts", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": []
}
```