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

> Options flow alerts: aggregates of option transactions that tripped a rule. See https://unusualwhales.com/option-flow-alerts/rules for rule definitions

Topic
messages**1**
routing**single type**
encoding**protobuf**

## Messages on this topic

[all messages
FlowAlert
An n aggregate of option transactions that tripped a rule, see [https://unusualwhales.com/option-flow-alerts/rules](https://unusualwhales.com/option-flow-alerts/rules)
45 fields→](/docs/kafka/types/FlowAlert)

All messages on this topic are of a single type.

## Consume the topic

```python Python theme={null}
from confluent_kafka import Consumer
from unusualwhales.schema_pb2 import FlowAlert

# CONFIG comes from the Connecting section of the Kafka overview.
consumer = Consumer(CONFIG | {"group.id": "my-flow-alerts-consumer"})
consumer.subscribe(["flow-alerts"])

while True:
    msg = consumer.poll(1.0)
    if msg is None or msg.error():
        continue

    event = FlowAlert()
    event.ParseFromString(msg.value())
    print(event)
```

> [!NOTE]
>
> `start_time`, `end_time`, and `executed_at` are Unix millisecond timestamps. `bid`, `ask`, `ivStart`, and `ivEnd` arrive as strings to preserve exact precision — parse them with a decimal type, not a float, if you are doing math on them.

## Example message

A decoded `FlowAlert`, with repeated fields truncated:

```json theme={null}
{
  "id": "5e0f1c8a-9a1e-4a5e-9f3e-2a7b6c1d8e40",
  "rule_id": "f0f4c0a1-33bd-4c1f-9b4a-8f1c9e2d7a11",
  "ticker": "SPY",
  "option_chain": "SPY241227C00480000",
  "underlying_price": 476.31,
  "price": 4.85,
  "bid": "4.80",
  "ask": "4.90",
  "volume": 41203,
  "open_interest": 18877,
  "volume_oi_ratio": 2.18,
  "total_size": 2500,
  "total_premium": 1212500.0,
  "total_ask_side_prem": 1100300.0,
  "total_bid_side_prem": 112200.0,
  "ask_vol": 2270,
  "bid_vol": 230,
  "mid_vol": 0,
  "no_side_vol": 0,
  "has_sweep": true,
  "has_floor": false,
  "has_multileg": false,
  "has_singleleg": true,
  "all_opening_trades": true,
  "trade_count": 14,
  "expiry_count": 1,
  "start_time": 1735059600000,
  "end_time": 1735059660000,
  "executed_at": 1735059657413,
  "trade_ids": ["9c1f...", "b47a..."],
  "exchanges": ["CBOE", "PHLX"],
  "upstream_condition_details": ["INTERMARKET_SWEEP"],
  "ivStart": "0.1842",
  "ivEnd": "0.1907",
  "url": "https://unusualwhales.com/flow/5e0f1c8a-9a1e-4a5e-9f3e-2a7b6c1d8e40"
}
```

> [!TIP]
>
> `trade_ids` holds the UUIDs of the individual transactions behind the alert. Consume [`all-option-trades`](/docs/kafka/topics/all-option-trades) alongside this topic to join an alert back to its component trades.