# Flow Alerts

`GET` `https://api.unusualwhales.com/api/option-trades/flow-alerts`

Flow alerts are rule based aggregations on the full tape of option trades. 

While there are quite a few different rules and alerts the most used one is the repeated hit family:
RepeatedHits, RepeatedHitsAscendingFill, RepeatedHitsDescendingFill

Each of those represent an alert when there have been multiple transactions on the same option contract
within a few milliseconds. This can be mean that a single order is being matched across multiple other orders
and creating multiple transactions. It can also just mean that there are multiple buyers/sellers at the same time. 

Trades usually use the repeated hits with other data points to form a picture on whether there is some urgency 
in entering/exiting a position in a contract/ticker.

The full current options tape including trades that do not form a RepeatedHits alert can be accessed through the
[Option Trades endpoint](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index). By setting `include_agg_trades` to true
in the option trades endpoint you would also retrieve the RepeatedHits from this endpoint.

The difference between the 3 repeated hits alerts are:
- DescendingFill: Each transaction that comes after another in chronological order has either the same fill price as or a lower fill price than the previous transaction. The last transaction must be lower than the first transaction.
- AscendingFill: The opposite of DescendingFill. The fill prices increase instead of decreasing.
- RepeatedHits (neither ascending nor descending): When it does not fit into one of the first two categories.

To express ascending and descending in a mathmatical notion. Let p₁, p₂, …, pₙ be the fill prices of n transactions ordered chronologically:
- DescendingFill: pᵢ ≥ pᵢ₊₁ for all i ∈ [1, n−1], and pₙ < p₁.
- AscendingFill: pᵢ ≤ pᵢ₊₁ for all i ∈ [1, n−1], and pₙ > p₁.

For the individual flow alert rules and how the aggregation is based on you can
checkout out [https://unusualwhales.com/option-flow-alerts/rules](https://unusualwhales.com/option-flow-alerts/rules).

For any given flow alert you can take a look at the individual trades that are making up the alert by taking the alert's id
and use [https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alert](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alert)
to retrieve the individual transactions.

For real time streaming of flow alerts, subscribe to the `flow-alerts` websocket channel, see [https://api.unusualwhales.com/docs/operations/PublicApi.SocketController.flow_alerts](https://api.unusualwhales.com/docs/operations/PublicApi.SocketController.flow_alerts).



## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Query Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `ticker_symbol` | Ticker | No | A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. |
| `unusual` | boolean | No | Convenience preset for "unusual" flow, matching the [live options flow](https://unusualwhales.com/live-options-flow) default criteria: volume>OI, size>OI, all-opening, OTM, single-leg, DTE≤60, ask-side≥50%, premium≥$10k, size≥5, issue types ADR/Common Stock/ETF. Applied as defaults, so any of those filters you pass explicitly (e.g. `min_ask_perc=0.9`, `max_dte=40`) overrides the preset. |
| `min_premium` |  | No | The minimum premium on that alert. Min: 0. |
| `max_premium` |  | No | The maximum premium on that alert. Min: 0. |
| `min_size` |  | No | The minimum size on that alert. Size is defined as the sum of the sizes of all transactions that make up the alert. Min: 0. |
| `max_size` |  | No | The maximum size on that alert. Min: 0. |
| `min_volume` |  | No | The minimum volume on that alert's contract at the time of the alert. Min: 0. |
| `max_volume` |  | No | The maximum volume on that alert's contract at the time of the alert. Min: 0. |
| `min_open_interest` |  | No | The minimum open interest on that alert's contract at the time of the alert. Min: 0. |
| `max_open_interest` |  | No | The maximum open interest on that alert's contract at the time of the alert. Min: 0. |
| `all_opening` |  | No | Boolean flag whether all transactions are opening transactions based on OI, Size & Volume. Since Flow Alerts with rule_name values of RepeatedHits, RepeatedHitsAscendingFill, and RepeatedHitsDescendingFill are composed of many individual transactions, it is extremely unlikely that the all_opening value will be true, so if you are interested in these Flow Alerts you should not set this query param to true. |
| `is_floor` |  | No | Boolean flag whether a transaction is from the floor. |
| `is_sweep` |  | No | Boolean flag whether a transaction is a intermarket sweep. |
| `is_call` |  | No | Boolean flag whether a transaction is a call. |
| `is_put` |  | No | Boolean flag whether a transaction is a put. |
| `is_ask_side` |  | No | Boolean flag whether a transaction is ask side. |
| `is_bid_side` |  | No | Boolean flag whether a transaction is bid side. |
| `rule_name[]` | Rule Name | No | An array of 1 or more rule name. |
| `min_diff` | Min Contract Diff | No | The minimum OTM diff of a contract.
Given a strike price of 120 and an underlying price of 98
the diff for a call option would equal to:
(120 - 98) / 98 = 0.2245

The diff for a put option would equal to:
-1 * (120 - 98) / 98 = -0.2245.
 |
| `max_diff` | Min Contract Diff | No | The minimum OTM diff of a contract.
Given a strike price of 120 and an underlying price of 98
the diff for a call option would equal to:
(120 - 98) / 98 = 0.2245

The diff for a put option would equal to:
-1 * (120 - 98) / 98 = -0.2245.
 |
| `min_volume_oi_ratio` | Min Volume OI Ratio | No | The minimum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 10, then a contract with zero open interest and 7 volume will NOT be included in your results. |
| `max_volume_oi_ratio` | Max Volume OI Ratio | No | The maximum ratio of contract volume to contract open interest. If the open interest of a contract is zero, then this ratio is evaluated as if the open interest of the contract was one (to avoid divide by zero errors). For example, if you set this ratio to 50, then a contract with zero open interest and 75 volume will NOT be included in your results. |
| `is_otm` | Is OTM Contract | No | Only include contracts which are currently out of the money. |
| `issue_types[]` | Issue types | No | An array of 1 or more issue types. |
| `min_dte` | Min DTE | No | The minimum days to expiry. Min: 0. |
| `max_dte` | Max DTE | No | The maximum days to expiry. Min: 0. |
| `min_ask_perc` | Flow Alerts Min Ask Percentage | No | The minimum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `max_ask_perc` | Flow Alerts Max Ask Percentage | No | The maximum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `min_bid_perc` | Flow Alerts Min Bid Percentage | No | The minimum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `max_bid_perc` | Flow Alerts Max Bid Percentage | No | The maximum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `min_bull_perc` | Flow Alerts Min Bull Percentage | No | The minimum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `max_bull_perc` | Flow Alerts Max Bull Percentage | No | The maximum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `min_bear_perc` | Flow Alerts Min Bear Percentage | No | The minimum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `max_bear_perc` | Flow Alerts Max Bear Percentage | No | The maximum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `min_skew` | Flow Alerts Min Skew | No | The minimum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `max_skew` | Flow Alerts Max Skew | No | The maximum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. |
| `min_price` | Flow Alerts Min Price | No | The minimum price of the underlying asset. Min: 0. |
| `max_price` | Flow Alerts Max Price | No | The maximum price of the underlying asset. Min: 0. |
| `min_iv_change` | Flow Alerts Min IV Change | No | The minimum IV change. Unbounded decimal proxy for percentage (e.g., 0.01 for minimum +1% change). |
| `max_iv_change` | Flow Alerts Max IV Change | No | The maximum IV change. Unbounded decimal proxy for percentage (e.g., 0.05 for maximum +5% change). |
| `min_size_vol_ratio` | Flow Alerts Min Size Volume Ratio | No | The minimum size to volume ratio. Min: 0. |
| `max_size_vol_ratio` | Flow Alerts Max Size Volume Ratio | No | The maximum size to volume ratio. Min: 0. |
| `min_spread` | Flow Alerts Min Spread | No | The minimum spread. Min: 0. |
| `max_spread` | Flow Alerts Max Spread | No | The maximum spread. Min: 0. |
| `min_marketcap` | Min Marketcap | No | The minimum marketcap. Min: 0. |
| `max_marketcap` | Max Marketcap | No | The maximum marketcap. Min: 0. |
| `is_multi_leg` | Flow Alerts Is Multi Leg | No | Boolean flag whether the transaction is a multi-leg transaction. |
| `size_greater_oi` | Flow Alerts Size Greater Than Open Interest | No | Only include alerts where the size is greater than the open interest. |
| `vol_greater_oi` | Flow Alerts Volume Greater Than Open Interest | No | Only include alerts where the volume is greater than the open interest. |
| `min_days_between_expiry_and_earnings` | MinDaysBetweenExpiryAndEarnings | No | Minimum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `max_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used. |
| `max_days_between_expiry_and_earnings` | MaxDaysBetweenExpiryAndEarnings | No | Maximum value of (contract_expiry_date - underlying_next_earnings_date) in days. Negative = contract expires BEFORE earnings; zero = same day; positive = AFTER earnings. Use together with `min_days_between_expiry_and_earnings` to target a window around the next earnings announcement. Examples: to exclude contracts that expire after the next earnings, set `max_days_between_expiry_and_earnings=-1`. To target contracts that expire the same week as (and after) earnings, set `min_days_between_expiry_and_earnings=1&max_days_between_expiry_and_earnings=6`. Contracts whose underlying has no known next earnings date are excluded whenever this filter is used. |
| `newer_than` | NewerThan | No | The unix time in milliseconds or seconds at which no older results will be returned. Can be used with `older_than` to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25). |
| `older_than` | OlderThan | No | The unix time in milliseconds or seconds at which no newer results will be returned. Can be used with `newer_than` to paginate by time. Also accepts an ISO date or RFC 3339 datetime (example: 2024-01-25). |
| `limit` | Default 100 Max 200 Min 1 | No | How many items to return. Default: 100. Max: 200. Min: 1. |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `alert_rule` | Alert Rule Name | The name of the alert rule. |
| `all_opening_trades` | Option Contract All Opening Trades |  |
| `created_at` | General UTC Timestamp | A UTC timestamp. |
| `expiry` | Option Contract Expiry | The contract expiry date in ISO format. |
| `expiry_count` | Option Contract Expiry Count | The amount of expiries belonging to the trade. This is only greater than 1 if it is a multileg trade. |
| `has_floor` | Option Contract Has Floor |  |
| `has_multileg` | Single Trade Has Multileg | Whether the trade is a multileg trade. |
| `has_singleleg` | Single Trade Is Single Leg | Whether the trade is a singleleg trade. |
| `has_sweep` | Single Trade Is Sweep | Whether the trade is a sweep. |
| `issue_type` | Stock Issue Type | The issue type of the ticker. |
| `open_interest` | ToBeDone |  |
| `option_chain` | Option Contract Symbol | The option symbol of the contract.

You can use the following regex to extract underlying ticker, option type, expiry & strike:
`^(?<symbol>[\w]*)(?<expiry>(\d{2})(\d{2})(\d{2}))(?<type>[PC])(?<strike>\d{8})$`

Keep in mind that the strike needs to be multiplied by 1,000.
 |
| `price` | ToBeDone |  |
| `strike` | Option Contract Strike | The contract strike. |
| `ticker` | ToBeDone |  |
| `total_ask_side_prem` | ToBeDone |  |
| `total_bid_side_prem` | ToBeDone |  |
| `total_premium` | ToBeDone |  |
| `total_size` | ToBeDone |  |
| `trade_count` | ToBeDone |  |
| `type` | Option Contract Type | The contract type. |
| `underlying_price` | ToBeDone |  |
| `volume` | ToBeDone |  |
| `volume_oi_ratio` | ToBeDone |  |


## Example

### curl

```bash
curl -X GET "https://api.unusualwhales.com/api/option-trades/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/option-trades/flow-alerts", headers=headers)
response = conn.getresponse()
print(response.read().decode("utf-8"))
```

## Response Example

```json
{
  "data": [
    {
      "alert_rule": "RepeatedHits",
      "all_opening_trades": false,
      "created_at": "2023-12-12T16:35:52.168490Z",
      "expiry": "2023-12-22",
      "expiry_count": 1,
      "has_floor": false,
      "has_multileg": false,
      "has_singleleg": true,
      "has_sweep": true,
      "issue_type": "Common Stock",
      "open_interest": 7913,
      "option_chain": "MSFT231222C00375000",
      "price": "4.05",
      "strike": "375",
      "ticker": "MSFT",
      "total_ask_side_prem": "151875",
      "total_bid_side_prem": "405",
      "total_premium": "186705",
      "total_size": 461,
      "trade_count": 32,
      "type": "call",
      "underlying_price": "372.99",
      "volume": 2442,
      "volume_oi_ratio": "0.30860609124226"
    }
  ]
}
```