# Unusual Options Activity

`GET` `https://api.unusualwhales.com/api/option-activity/unusual`

Returns option contracts flagged as unusual — the API equivalent of the [live options flow](https://unusualwhales.com/live-options-flow) "unusual" view.

This is the [Hottest Chains](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.contract_screener) screener with the `unusual` preset applied by default: the contract-expressible subset of the live-options-flow criteria — volume > OI, out-of-the-money, DTE ≤ 60, ask-side ≥ 50%, premium ≥ $10k, issue types ADR/Common Stock/ETF.

Every Hottest Chains filter is accepted here and overrides the preset (e.g. `?min_premium=25000&max_dte=30`); pass `unusual=false` to return the full screen. For the complete list of filters and the response shape see the [Hottest Chains endpoint](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.contract_screener).

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

NOTE: Contracts with a volume of less than 200 are not being returned


## 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 `-`. |
| `sectors[]` | Sectors | No | An array of 1 or more sectors. |
| `unusual` | boolean | No | Whether to apply the unusual preset (volume>OI, OTM, DTE≤60, ask-side≥50%, premium≥$10k). Defaults to true for this endpoint; pass false to return the full screen. |
| `min_premium` | integer | No | The minimum total premium on the contract. |
| `max_dte` | integer | No | The maximum days to expiry. |
| `issue_types[]` | Issue types | No | An array of 1 or more issue types. |
| `order` | string | No | The field to order the results by. |
| `order_direction` | string | No | Whether to sort ascending or descending. Defaults to descending. |
| `limit` | integer | No | How many items to return. Defaults to 100. Max 200. |
| `date` | Optional Market Date | No | A trading date in the format of YYYY-MM-DD.
This is optional and by default the last trading date.
 |


## Response (200)

| Field | Type | Description |
|-------|------|-------------|
| `ask_side_volume` | Option Contract Ask Volume | The amount of volume that happened on the ask side.

Ask side is defined as (ask + bid) / 2 < fill price.
 |
| `avg_price` | Option Contract Avg Price | The volume weighted average fill price of the contract. |
| `bid_side_volume` | Option Contract Bid Volume | The amount of volume that happened on the bid side.

Bid side is defined as (ask + bid) / 2 > fill price.
 |
| `chain_prev_close` | Option Contract Previous Close Price | The previous trading day's contract price. |
| `close` | Option Contract Close | The last fill on the contract. |
| `cross_volume` | Option Contract Cross Volume | The amount of cross volume.
Cross volume consists of all transaction that have the cross trade code.
 |
| `er_time` | Stock Earnings time | The time when the earnings will be released. |
| `expiry` | Option Contract Expiry | The contract expiry date in ISO format. |
| `floor_volume` | Option Contract Floor Volume | The amount of floor volume.
Floor volume consists of all transaction that have the floor trade code.
 |
| `high` | Option Contract High | The highest fill on that contract. |
| `last_fill` | Option Contract Last Transaction Time | The last time there was a transaction for the given contract as UTC timestamp. |
| `low` | Option Contract Low | The lowest fill on that contract. |
| `mid_volume` | Option Contract Mid Volume | The amount of volume that happened in the middle of the ask and bid.

Mid is defined as (ask + bid) / 2 == fill price.
 |
| `multileg_volume` | Option Contract Multi Leg Volume | The amount of volume that happened as part of a multileg trade with another contract.
This can be spreads/rolls/condors/butterflies and more.
 |
| `next_earnings_date` | Stock Next Earnings Date | The next earnings date of the ticker. Null if either unknown as of now or if the ticker does not have any earnings such as an ETF |
| `no_side_volume` | Option Contract No Side Volume | The amount of volume that happened on no identifiable side.
This can be late, out of sequence and/or cross transactions.
 |
| `open` | Option Contract Open | The first fill on that contract. |
| `open_interest` | Option Contract Open interest | The open interest for the contract. |
| `option_symbol` | 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.
 |
| `option_type` | Option Contract Option Type | The option type of the contract. |
| `premium` | Option Contract Premium | The total option premium. |
| `sector` | Market General Sector | The financial sector of the ticker. Empty if unknown or not applicable such as ETF/Index. |
| `stock_multi_leg_volume` | Option Contract Stock Multi Leg Volume | The amount of volume that happened as part of a stock transaction and possibly other option contracts.
This can be covered calls and more.
 |
| `stock_price` | Stock Close Price | The close stock price of the ticker. |
| `strike` | Option Contract Strike | The contract strike. |
| `sweep_volume` | Option Contract Sweep Volume | The amount of sweep volume.
Sweep volume consists of all transaction that have the sweep trade code.
 |
| `ticker_vol` | Stock Total Volume | The total amount of options volume for the given ticker. |
| `total_ask_changes` | Option Contract Total Ask Changes | The total count of changes to the NBBO ask during that day's trading session. |
| `total_bid_changes` | Option Contract Total Bid Changes | The total count of changes to the NBBO bid during that day's trading session. |
| `trades` | Option Contract Total Trades Count | The amount of transaction for this contract. |
| `volume` | Option Contract Volume | The contract volume. |


## Example

### curl

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

## Response Example

```json
{
  "data": [
    {
      "ask_side_volume": 119403,
      "avg_price": "1.0465802437910297887119234370",
      "bid_side_volume": 122789,
      "chain_prev_close": "1.29",
      "close": "0.03",
      "cross_volume": 0,
      "er_time": "unknown",
      "expiry": "2023-09-08",
      "floor_volume": 142,
      "high": "2.95",
      "last_fill": "2023-09-08T17:45:32Z",
      "low": "0.02",
      "mid_volume": 22707,
      "multileg_volume": 7486,
      "next_earnings_date": "2023-10-18",
      "no_side_volume": 0,
      "open": "0.92",
      "open_interest": 18680,
      "option_symbol": "TSLA230908C00255000",
      "option_type": "call",
      "premium": "27723806.00",
      "sector": "Consumer Cyclical",
      "stock_multi_leg_volume": 52,
      "stock_price": "247.94",
      "strike": "255.0",
      "sweep_volume": 18260,
      "ticker_vol": 2546773,
      "total_ask_changes": 44343,
      "total_bid_changes": 43939,
      "trades": 39690,
      "volume": 264899
    }
  ]
}
```