> ## 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 `). 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 > 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). 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/websocket/flow-alerts](https://api.unusualwhales.com/docs/websocket/flow-alerts). The 14-day lookback limit on the custom alerts endpoint (`/api/alerts`) does not apply to this endpoint. ## OpenAPI ````yaml /openapi.yaml get /api/option-trades/flow-alerts openapi: 3.0.0 info: description: > For API Support or any questions email: support@unusualwhales.com Documentation for the official [UnusualWhales](https://unusualwhales.com) api ## Startup Tier Building a product on our data? Get started immediately with our self-serve Startup tier at $750/mo — 500 req/min, 80K daily requests, 90-day lookback, and commercial use included. Annual plan available at $7,500/yr (2 months free) with 1,000 req/min and 10 concurrent requests for market-open bursts. [Start building →](https://unusualwhales.com/checkout?plan=enterprise_startup&interval=monthly) Need Kafka streaming? Our Startup + Kafka tier at $3,000/mo adds real-time Kafka cluster access. Annual plan available at $30,000/yr (2 months free) with the same 1,000 req/min burst allowance. [Start building →](https://unusualwhales.com/checkout?plan=enterprise_startup_kafka&interval=monthly) ## Enterprise/Professional Subscribers For custom enterprise pricing, redistribution licenses, or bespoke solutions, email [oskar@unusualwhales.com, enterprise@unusualwhales.com or nastja.petrovic@unusualwhales.com](mailto:oskar@unusualwhales.com?cc=enterprise@unusualwhales.com,nastja.petrovic@unusualwhales.com). ## Changelog # 2026.09.28 - The websocket documentation moved to [https://api.unusualwhales.com/docs/websocket](https://api.unusualwhales.com/docs/websocket), with one page per channel. REST endpoints that serve the same data as a websocket channel link to that channel's page. # 2026.09.21 - Added a new websocket channel [`stock_screener`](https://api.unusualwhales.com/docs/websocket/stock-screener). It streams the latest stock screener row of every ticker and is the live counterpart of [`/screener/stocks`](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.stock_screener). # 2026.09.12 - Added a new websocket channel [`ta_1d_live:{TICKER}`](https://api.unusualwhales.com/docs/websocket/technical-analysis-indicators). The channel streams technical-analysis indicator values (moving averages, RSI, MACD, Bollinger bands, ADX, Aroon, ATR, CCI, MFI, OBV, stochastics and Williams %R) computed on daily candles for one ticker. During regular trading hours it resends the day that is still forming as the price moves, so the newest message for a `date` replaces the ones before it. An indicator reads as `null` until enough daily history exists to compute it. The `1d` in the name is the candle interval and `live` means the values track the open session. # 2026.09.04 - Added new websocket channels [`quotes` and `quotes:{TICKER}`](https://api.unusualwhales.com/docs/websocket/stock-quotes). They stream the live best bid and ask - for every ticker at once, or for a single ticker - and are the live counterpart of [`/stock/:ticker/quote`](https://api.unusualwhales.com/docs/operations/PublicApi.StockQuoteController.show). # 2026.09.01 - Added a global [`greeks`](https://api.unusualwhales.com/docs/websocket/greeks) websocket channel. It streams the same per-contract option greeks as `greeks:`, but for every underlying at once. This is a high volume firehose - prefer the per-ticker channel unless you need the full tape. # 2026.08.30 - MCP now advertises build guidance: `instructions` on initialize; builder prompts `build_dashboard_app`, `build_confluence_alert`, `build_trading_bot`, `build_data_stream`, `start_from_example`, and `setup_api_project`; tools `get_build_recipe` and `get_api_examples` (scripts from [https://github.com/unusual-whales/api-examples](https://github.com/unusual-whales/api-examples)); and `resources/list` / `resources/templates/list` / `resources/read` for playbooks and example files. # 2026.08.28 - Added a new websocket channel [`risk_reversal_skew`](https://api.unusualwhales.com/docs/websocket/risk-reversal-skew). The channel streams live 25- and 10-delta risk reversal skew (put implied volatility minus call implied volatility) per expiry across every ticker, the live counterpart of [`/stock/:ticker/historical-risk-reversal-skew`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.historical_risk_reversal_skew). The channel is global only; there is no per-ticker variant. # 2026.08.22 - Updated [`/stock/:ticker/gex-levels`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.gex_levels) to derive its levels from directionalized volume instead of a cumulative total over the static open-interest snapshot. - Added `date`, `time`, `source`, and `nearby_flips` to the [`/stock/:ticker/gex-levels`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.gex_levels) response. `nearby_flips` lists the five zero-gamma crossings nearest spot, ordered by distance from it. `time` is when the underlying exposure snapshot was calculated. # 2026.08.21 - Added new websocket channels [`interpolated_iv` and `interpolated_iv:TICKER`](https://api.unusualwhales.com/docs/websocket/interpolated-iv). The channels stream interpolated implied volatility and expected moves at fixed horizons (1-365 trading days), the live counterpart of [`/stock/:ticker/interpolated-iv`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.interpolated_iv). - Added new websocket channels [`iv_term_structure` and `iv_term_structure:TICKER`](https://api.unusualwhales.com/docs/websocket/iv-term-structure). The channels stream ATM implied volatility and expected moves per real option expiry — the raw entries behind `interpolated_iv` — the live counterpart of [`/stock/:ticker/volatility/term-structure`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.implied_volatility_term_structure). # 2026.04.30 Added a new advanced-tier endpoint group. All routes below require API Advanced, Enterprise Startup, Enterprise Startup + Kafka, or Enterprise tier. ### Company fundamentals - Added [`/companies/:ticker/profile`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.profile) for sector, industry, market cap, P/E, EPS, dividend yield, analyst targets, 52-week range, moving averages, and the full analyst rating breakdown. - Added [`/companies/:ticker/dividends`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.dividends) for historical dividend events. - Added [`/companies/:ticker/splits`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.splits) for historical stock-split events. - Added [`/companies/:ticker/earnings-estimates`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.earnings_estimates) for forward analyst earnings and revenue estimates by quarter and year. - Added [`/companies/:ticker/transcripts/:quarter`](https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.transcript) for earnings-call transcripts with speakers, statements, and per-statement sentiment. - Added [`/companies/listings`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.listings) for the master list of US-traded securities (active or delisted). ### Macro - Added [`/commodities/:name`](https://api.unusualwhales.com/docs/operations/PublicApi.CommoditiesController.show) for long-running price series across WTI, Brent, natural gas, copper, aluminum, wheat, corn, cotton, sugar, coffee, and the global commodities index. - Added [`/economy/:indicator`](https://api.unusualwhales.com/docs/operations/PublicApi.EconomyController.show) for US economic indicator series (GDP, GDP per capita, treasury yield, fed funds rate, CPI, inflation, retail sales, durables, unemployment, payrolls). ### Forex - Added [`/forex/rate`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.rate) for live FX spot rates with bid and ask. - Added [`/forex/intraday`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.intraday) for 1min through 60min FX OHLC bars. - Added [`/forex/history`](https://api.unusualwhales.com/docs/operations/PublicApi.ForexController.history) for daily, weekly, and monthly FX OHLC bars. ### Digital currencies - Added [`/digital-currencies/intraday`](https://api.unusualwhales.com/docs/operations/PublicApi.DigitalCurrenciesController.intraday) for intraday OHLC bars priced against a fiat market. - Added [`/digital-currencies/history`](https://api.unusualwhales.com/docs/operations/PublicApi.DigitalCurrenciesController.history) for daily, weekly, and monthly OHLC bars. ### Market intel and analytics - Added [`/market/movers`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.movers) for pre-ranked top gainers, top losers, and most actively traded US tickers. - Added [`/calendar/ipo`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.ipo_calendar) for upcoming IPOs over the next 3 months. - Added [`/analytics/window`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.analytics_window) for fixed-window statistical analytics across baskets of tickers (mean, stddev, correlation, drawdown, autocorrelation, covariance, and more). - Added [`/analytics/sliding`](https://api.unusualwhales.com/docs/operations/PublicApi.IntelController.analytics_sliding) for sliding-window statistical analytics. ### Congressional unusual trades (scope `unusual-trades`) - Added [`/congress/unusual-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.recent) for unusual congressional trades filtered by reason tag (committee_conflict, first_person_to_trade, low_marketcap, unusual_industry, unusually_large_trade, fec_donation_conflict). - Added [`/congress/unusual-trades/by-tickers`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.by_tickers) with ticker, transaction type, date range, and politician filters. - Added [`/congress/unusual-trades/chart-data`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.chart_data) returning trade points with SPY benchmark closes. - Added [`/congress/unusual-trades/stats`](https://api.unusualwhales.com/docs/operations/PublicApi.UnusualTradesController.stats) for aggregate overview statistics. ### Private markets (scope `private-markets`) - Added [`/private-markets/companies`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.companies) for the full Nasdaq Private Markets company list with sector and name filters. - Added [`/private-markets/companies/:npm_ticker`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.company_profile) for the company profile with latest price, total funding, and investor count. - Added [`/private-markets/companies/:npm_ticker/funding`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.funding) for funding round history. - Added [`/private-markets/companies/:npm_ticker/investors`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.investors) for disclosed investors. - Added [`/private-markets/companies/:npm_ticker/management`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.management) for disclosed leadership. - Added [`/private-markets/companies/:npm_ticker/pricing`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.pricing) for historical implied per-share pricing. - Added [`/private-markets/investors`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.top_investors) for top investors ranked by distinct company count. - Added [`/private-markets/investors/:name`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.investor_profile) for an investor's portfolio. - Added [`/private-markets/search`](https://api.unusualwhales.com/docs/operations/PublicApi.PrivateMarketsController.search) for substring search across companies and investors. ### MCP - Added 5 premium MCP catalogs covering the new endpoints: `uw_companies_extras`, `uw_macro`, `uw_forex`, `uw_digital_currencies`, `uw_intel`. Plus `uw_unusual_trades` and `uw_private_markets` for the scope-gated catalogs above. - Premium MCP catalogs and individual premium commands (`uw_stock.ownership`, `uw_flow.full_tape`, `uw_politicians`) are now hidden by default. Operators opt in via `UW_ENABLE_PREMIUM_TOOLS=true` (all on) or `UW_PREMIUM_TOOLS=uw_companies_extras,uw_macro,...` (per-tool allowlist supporting `` or `.` form). # 2026.04.29 - Added MCP tool `get_short_volume_ratio_by_exchange` for [`/shorts/:ticker/volumes-by-exchange`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_by_exchange) data. - Added MCP tool `get_short_volume_ratio_by_ticker` for [`/shorts/:ticker/volume-and-ratio`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_volume_and_ratio) data. - Added MCP tool `get_short_screener` for [`/short_screener`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_screener) - Added MCP tool `get_short_data_by_ticker` for [`/shorts/:ticker/data`](https://api.unusualwhales.com/docs/operations/PublicApi.ShortController.short_data) # 2026.04.14 - Enhanced MCP [`/api/mcp`](https://api.unusualwhales.com/docs) `tools/call` validation to reject unsupported arguments, missing required arguments, and invalid enum values before tool execution. - MCP tool errors now include retry guidance telling clients to inspect `tools/list` `inputSchema` and retry with supported arguments. # 2026.03.02 - Added authenticated MCP endpoint [`/api/mcp`](https://api.unusualwhales.com/docs) to expose existing AI tools to API subscribers using the same `Authorization: Bearer ` flow. - Supports MCP `initialize`, `tools/list`, and `tools/call` methods backed by the existing internal tool registry and execution pipeline. # 2026.01.20 - Updated interest-float endpoint with new version and deprecated old version - [`/shorts/:ticker/interest-float/v2`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_interest_and_float_v2) - Added interest-float search screener endpoint - [`/short_screener`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_screener) # 2025.09.23 - Added new websocket channels [`lit_trades`](https://api.unusualwhales.com/docs/websocket/lit-trades) and [`off_lit_trades`](https://api.unusualwhales.com/docs/websocket/off-lit-trades) to stream live lit (exchange-based) and off-lit (dark pool) trades respectively. # 2025.09.22 - Added `newer_than` and `older_than` time filtering parameters to [`/alerts`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts) endpoint with 14-day maximum lookback period for custom alerts queries # 2025.08.20 - Added [`/market/top-net-impact`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.top_net_impact) endpoint to get the top tickers by net premium (split between bullish and bearish). Supports filtering by `issue_types[]`, `date`, and `limit` (default 20, max 100). # 2025.06.18 - Added [`/market/:sector/sector-tide`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.sec_indst) endpoint to get the market tide for a specific sector # 2025.06.02 - Added [`/stock/:ticker/interpolated-iv`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.interpolated_iv) endpoint to get the interpolated iv for various days # 2025.05.29 - Added [`/option-contract/:id/volume-profile`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.volume_profile) endpoint to get the volume profile of an option contract (volume by fill price) # 2025.05.23 - Added [`/option-contract/:id/intraday`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.intraday) endpoint to get the volume, premium & OHLC for a contract in 1min ticks for a given trading day # 2025.05.07 - Added `prev_close_price` field to [`/stock/:ticker/stock-state`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.last_stock_state) endpoint to provide the previous close price. # 2025.04.30 - Enhanced [`/option-trades/full-tape/{date}`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionTradeController.full_tape) to allow users with `websocket` scope to access the last two trading days of data # 2025.04.23 - Added [`/net-flow/expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.NetFlowController.expiry) endpoint to track net premium flow by tide type, moneyness, and expiration categories. This powers charts like those found on the [zero-DTE dashboard](https://unusualwhales.com/zero-dte) # 2025.04.08 - Enhanced [`/market/correlations`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.correlations) endpoint with new date filtering options: `start_date` and `end_date` parameters to specify custom date ranges, complementing the existing `interval` parameter # 2025.03.23 - Updated [`/stock/{ticker}/net-prem-ticks`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.net_prem_ticks) endpoint to include `call_volume`, `put_volume`, `call_volume_bid_side`, `put_volume_bid_side`, `call_volume_ask_side`, `put_volume_ask_side` & `net_delta`. # 2025.03.10 - Added [`/news/headlines`](https://api.unusualwhales.com/docs#/operations/PublicApi.NewsController.headlines) endpoint to access financial news headlines with filtering capabilities - Added Shorts API endpoints: - [`/shorts/:ticker/data`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_data) - [`/shorts/:ticker/volumes-by-exchange`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_volume_by_exchange) - [`/shorts/:ticker/ftds`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.failures_to_deliver) - [`/shorts/:ticker/interest-float`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_interest_and_float) - [`/shorts/:ticker/volume-and-ratio`](https://api.unusualwhales.com/docs#/operations/PublicApi.ShortController.short_volume_and_ratio) # 2025.02.19 - The endpoint [`/stock/:ticker/spot-exposures/:expiry/strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry) has been deprecated and been replaced by [`/stock/:ticker/spot-exposures/expiry-strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry_v2) To migrate over replace all your `/api/stock/:ticker/spot-exposures/:expiry/strike` calls with `/api/stock/:ticker/spot-exposures/expiry-strike?expirations[]=expiry` # 2025.02.13 - The endpoint `/congress/recent-reports` has been removed as it returns the same data as `/congress/recent-trades`. # 2025.02.05 - Enhanced [`/market/fda-calendar`](https://api.unusualwhales.com/docs#/operations/PublicApi.MarketController.fda_calendar) with better FDA data, additional fields (notes, outcomes, sources), and filtering by company metrics # 2025.02.03 - Updated dark pool/off lit endpoints to allow filtering for size, premium & consolidated volume # 2025.01.22 - Added [`gex_strike_expiry:`](https://api.unusualwhales.com/docs/websocket/gex) channel to the websocket - Added `call_option_symbol` & `put_option_symbol` to [`/stock/{ticker}/greeks`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greeks) # 2025.01.16 - Added [`/stock/:ticker/spot-exposures/:expiry/strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.spot_exposures_by_strike_expiry) # 2024.12.11 - Added [`/alerts/configuration`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.configs) - Added [`/alerts`](https://api.unusualwhales.com/docs#/operations/PublicApi.AlertsController.alerts) This allows one to grab all the alerts that have been triggerd for any alert that one has configured. With an existing unusualwhales account you can view and configure alerts directly on the [website](https://unusualwhales.com/custom-alerts) # 2024.12.02 - Added [`/stock/:ticker/oi-per-strike`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.oi_per_strike) - Added [`/stock/:ticker/oi-per-expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.oi_per_expiry) # 2024.11.19 - Improved all earnings endpoint # 2024.11.09 - Added `perc_of_total` & `perc_of_share_value` to [`/institution/:name/holdings`](https://api.unusualwhales.com/docs#/operations/PublicApi.InstitutionController.holdings) # 2024.10.30 - Added [`/stock/:ticker/nope`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.nope) # 2024.10.28 - Added [`/group-flow/:flow_group/greek-flow`](https://api.unusualwhales.com/docs#/operations/PublicApi.GroupFlowController.greek_flow) - Added [`/group-flow/:flow_group/greek-flow/:expiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.GroupFlowController.greek_flow_expiry) - Added [`/stock/:ticker/greek-flow`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greek_flow) - Added [`/stock/:ticker/greek-flow/:epxiry`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.greek_flow_expiry) # 2024.10.16 - Added etf inflow & outflow endpoint [`/etfs/:ticker/in_outflow`](PublicApi.EtfController.in_outflow) # 2024.10.15 - Added institutional latest filings endpoint [`/institution/latest_filings`](PublicApi.InstitutionController.latest_filings) - Added institutional ownership endpoint [`/institution/:ticker/ownership`](PublicApi.InstitutionController.ownership) # 2024.10.14 - Added 2 new fields: `days_of_oi_increases` & `days_of_vol_greater_than_oi` to [`/market/oi-change`](PublicApi.MarketController.oi_change) ``` days_of_oi_increases: The number of consecutive days that the open interest has increased for this contract. If on any day the open interest decreases or does not change the count will reset. days_of_vol_greater_than_oi: The number of consecutive days that the volume has been greater than the open interest for this contract. If on any day the volume is less than or equal to the open interest the count will reset. ```
# 2024.10.10 - Added institutional activity endpoint [`/institution/:name/activity`](PublicApi.InstitutionController.activity) # 2024.10.09 - Added institutional list endpoint [`institutions`](PublicApi.InstitutionController.list) - Added institutional holdings endpoint [`/institution/:name/holdings`](PublicApi.InstitutionController.holdings) - Added institutional sector exposure endpoint [`/institution/:name/sectors`](PublicApi.InstitutionController.sectors) # 2024.08.01 - Added new flow per strike intraday endpoint [`/stock/:ticker/flow-per-strike-intraday`](PublicApi.TickerController.flow_per_strike_intraday) # 2024.07.11 - Added new correlation endpoint [`/market/correlations?tickers=SPY,QQQ,JPM,BAC`](PublicApi.MarketController.correlations) # 2024.05.30 - Added the ability to filter [`/darkpool/:ticker`](PublicApi.DarkPoolController.darkpool_ticker) by timestamps through the two new query parameters `older_than` and `newer_than` # 2024.05.21 - Added directionalized volume fields to [`/stock/:ticker/spot-exposures`](PublicApi.TickerController.spot_exposures_one_minute) and [`/stock/:ticker/spot-exposures/strike`](PublicApi.TickerController.spot_exposures_by_strike) # 2024.05.17 - Added the channels `gex:TICKER` & `gex_strike:TICKER` to the [websocket](https://api.unusualwhales.com/docs/websocket) # 2024.05.07 - Added the ability to filter [`/option-trades/flow-alerts`](PublicApi.OptionTradeController.flow_alerts) by timestamps through the two new query parameters `older_than` and `newer_than` # 2024.05.06 - Added endpoint [`/stock/:ticker/stock-state`](PublicApi.TickerController.last_stock_state) to retrieve the last stock price & volume - Added endpoint [`/stock/:ticker/volatility/realized`](PublicApi.TickerController.realized_volatility) to retrieve a stock's realized volatility # 2024.05.03 - The data returned by /stock/:ticker/option-contracts has been limited to 500 results # 2024.05.02 - Added endpoint [`/market/:ticker/etf-tide`](PublicApi.MarketController.etf_tide) # 2024.05.01 - Added endpoint [`/stock/:ticker/spot-exposures/strike`](PublicApi.TickerController.spot_exposures_by_strike) - Added new channel [`price:TICKER`](https://api.unusualwhales.com/docs/websocket) to the websocket. The channel will push live price updates for the given ticker. # 2024.04.25 - Added endpoint [`/stock/:ticker/greek-exposure/strike`](PublicApi.TickerController.greek_exposure_by_strike) - Added endpoint [`/stock/:ticker/greek-exposure/expiry`](PublicApi.TickerController.greek_exposure_by_expiry) - Added endpoint [`/stock/:ticker/greek-exposure/strike-expiry`](PublicApi.TickerController.greek_exposure_by_strike_expiry) # 2024.03.28 - Fixed field name volatility -> risk_reversal for endpoint [`/stock/:ticker/historical_risk_reversal_skew`](PublicApi.TickerController.historical_risk_reversal_skew) # 2024.03.26 - Added endpoint [`/stock/:ticker/greeks`](PublicApi.TickerController.greeks) - Added endpoint [`/stock/:ticker/historical_risk_reversal_skew`](PublicApi.TickerController.historical_risk_reversal_skew) # 2024.03.23 - BREAKING CHANGE: Previously `/option-contract/:id/flow` would return the data as a json list. This has been now changed so that the endpoint returns the data in the format `{"data": [], "date": "2024-03-22"}`. Secondly, the endpoint will now only return data for a single trading day. # 2024.03.06 - Added endpoint [`/option-trades/flow-alerts`](PublicApi.OptionTradeController.flow_alerts) - Added flow-alerts streaming to the WebSocket. # 2024.03.04 - Added endpoint [`/stock/:ticker/max-pain`](https://api.unusualwhales.com/docs#/operations/PublicApi.TickerController.max_pain) # 2024.02.16 - Added new endpoint section [`Seasonality`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.market_seasonality) with new endpoints: - [`/seasonality/market`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.market_seasonality) - [`/seasonality/:month/performers`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.month_performers) - [`/seasonality/:ticker/monthly`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.monthly) - [`/seasonality/:ticker/year-month`](https://api.unusualwhales.com/docs#/operations/PublicApi.SeasonalityController.year_month) # 2024.02.07 - Added endpoints [`/stock/:ticker/expiry-breakdown`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.expiry_breakdown) & [`/stock/:ticker/option-contracts`](https://api.unusualwhales.com/docs#/operations/PublicApi.OptionContractController.option_contracts). These 2 endpoints allow access to the data located here: [https://unusualwhales.com/stock/AAPL/option-chains](https://unusualwhales.com/stock/AAPL/option-chains) title: UnusualWhales Api version: '1.0' servers: - url: https://api.unusualwhales.com variables: {} security: - authorization: [] tags: [] paths: /api/option-trades/flow-alerts: get: tags: - option-trade summary: Flow Alerts description: > 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). 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/websocket/flow-alerts](https://api.unusualwhales.com/docs/websocket/flow-alerts). The 14-day lookback limit on the custom alerts endpoint (`/api/alerts`) does not apply to this endpoint. operationId: PublicApi.OptionTradeController.flow_alerts parameters: - description: '' in: query name: ticker_symbol required: false schema: $ref: '#/components/schemas/Ticker' - description: >- 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. in: query name: unusual required: false schema: type: boolean - description: '' in: query name: min_premium required: false schema: description: 'The minimum premium on that alert. Min: 0.' example: 12500.5 minimum: 0 type: integer - description: '' in: query name: max_premium required: false schema: description: 'The maximum premium on that alert. Min: 0.' example: 12500.5 minimum: 0 type: integer - description: '' in: query name: min_size required: false schema: description: >- 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. example: 125 minimum: 0 type: integer - description: '' in: query name: max_size required: false schema: description: 'The maximum size on that alert. Min: 0.' example: 125 minimum: 0 type: integer - description: '' in: query name: min_volume required: false schema: description: >- The minimum volume on that alert's contract at the time of the alert. Min: 0. example: 125 minimum: 0 type: integer - description: '' in: query name: max_volume required: false schema: description: >- The maximum volume on that alert's contract at the time of the alert. Min: 0. example: 125 minimum: 0 type: integer - description: '' in: query name: min_open_interest required: false schema: description: >- The minimum open interest on that alert's contract at the time of the alert. Min: 0. example: 125 minimum: 0 type: integer - description: '' in: query name: max_open_interest required: false schema: description: >- The maximum open interest on that alert's contract at the time of the alert. Min: 0. example: 125 minimum: 0 type: integer - description: '' in: query name: all_opening required: false schema: default: true description: >- 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. example: true type: boolean - description: '' in: query name: is_floor required: false schema: default: true description: Boolean flag whether a transaction is from the floor. example: true type: boolean - description: '' in: query name: is_sweep required: false schema: default: true description: Boolean flag whether a transaction is a intermarket sweep. example: true type: boolean - description: '' in: query name: is_call required: false schema: default: true description: Boolean flag whether a transaction is a call. example: true type: boolean - description: '' in: query name: is_put required: false schema: default: true description: Boolean flag whether a transaction is a put. example: true type: boolean - description: '' in: query name: is_ask_side required: false schema: default: true description: Boolean flag whether a transaction is ask side. example: true type: boolean - description: '' in: query name: is_bid_side required: false schema: default: true description: Boolean flag whether a transaction is bid side. example: true type: boolean - description: '' in: query name: rule_name[] required: false schema: $ref: '#/components/schemas/Rule_Name' - description: '' in: query name: min_diff required: false schema: $ref: '#/components/schemas/Min_Contract_Diff' - description: '' in: query name: max_diff required: false schema: $ref: '#/components/schemas/Min_Contract_Diff' - description: '' in: query name: min_volume_oi_ratio required: false schema: $ref: '#/components/schemas/Min_Volume_OI_Ratio' - description: '' in: query name: max_volume_oi_ratio required: false schema: $ref: '#/components/schemas/Max_Volume_OI_Ratio' - description: '' in: query name: is_otm required: false schema: $ref: '#/components/schemas/Is_OTM_Contract' - description: '' in: query name: issue_types[] required: false schema: $ref: '#/components/schemas/Issue_types' - description: '' in: query name: min_dte required: false schema: $ref: '#/components/schemas/Min_DTE' - description: '' in: query name: max_dte required: false schema: $ref: '#/components/schemas/Max_DTE' - description: '' in: query name: min_ask_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Ask_Percentage' - description: '' in: query name: max_ask_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Ask_Percentage' - description: '' in: query name: min_bid_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Bid_Percentage' - description: '' in: query name: max_bid_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Bid_Percentage' - description: '' in: query name: min_bull_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Bull_Percentage' - description: '' in: query name: max_bull_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Bull_Percentage' - description: '' in: query name: min_bear_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Bear_Percentage' - description: '' in: query name: max_bear_perc required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Bear_Percentage' - description: '' in: query name: min_skew required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Skew' - description: '' in: query name: max_skew required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Skew' - description: '' in: query name: min_price required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Price' - description: '' in: query name: max_price required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Price' - description: '' in: query name: min_iv_change required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_IV_Change' - description: '' in: query name: max_iv_change required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_IV_Change' - description: '' in: query name: min_size_vol_ratio required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Size_Volume_Ratio' - description: '' in: query name: max_size_vol_ratio required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Size_Volume_Ratio' - description: '' in: query name: min_spread required: false schema: $ref: '#/components/schemas/Flow_Alerts_Min_Spread' - description: '' in: query name: max_spread required: false schema: $ref: '#/components/schemas/Flow_Alerts_Max_Spread' - description: '' in: query name: min_marketcap required: false schema: $ref: '#/components/schemas/Min_Marketcap' - description: '' in: query name: max_marketcap required: false schema: $ref: '#/components/schemas/Max_Marketcap' - description: '' in: query name: is_multi_leg required: false schema: $ref: '#/components/schemas/Flow_Alerts_Is_Multi_Leg' - description: '' in: query name: size_greater_oi required: false schema: $ref: '#/components/schemas/Flow_Alerts_Size_Greater_Than_Open_Interest' - description: '' in: query name: vol_greater_oi required: false schema: $ref: '#/components/schemas/Flow_Alerts_Volume_Greater_Than_Open_Interest' - description: '' in: query name: min_days_between_expiry_and_earnings required: false schema: $ref: '#/components/schemas/MinDaysBetweenExpiryAndEarnings' - description: '' in: query name: max_days_between_expiry_and_earnings required: false schema: $ref: '#/components/schemas/MaxDaysBetweenExpiryAndEarnings' - description: '' in: query name: newer_than required: false schema: $ref: '#/components/schemas/NewerThan' - description: '' in: query name: older_than required: false schema: $ref: '#/components/schemas/OlderThan' - description: '' in: query name: limit required: false schema: $ref: '#/components/schemas/Default_100_Max_200_Min_1' responses: '200': content: application/json: schema: $ref: '#/components/schemas/Flow_Alert' description: '' '401': content: application/json: schema: $ref: '#/components/schemas/Authentication_Error' description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden_Error' description: Forbidden '422': content: application/json: schema: $ref: '#/components/schemas/Error_Message' description: Unprocessable Entity '500': content: text/plain: schema: $ref: >- #/components/schemas/Error_Message_on_an_internal_server_error. description: Internal Server Error callbacks: {} components: schemas: Ticker: description: >- A comma separated list of tickers. To exclude certain tickers prefix the first ticker with a `-`. example: AAPL,INTC title: Ticker type: string Rule_Name: description: An array of 1 or more rule name. example: - RepeatedHits - RepeatedHitsAscendingFill items: $ref: '#/components/schemas/Flow_alert_rule' title: Rule Name type: array Min_Contract_Diff: description: | 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. example: 0.53 title: Min Contract Diff type: string Min_Volume_OI_Ratio: description: >- 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. example: 0.32 minimum: 0 title: Min Volume OI Ratio type: number Max_Volume_OI_Ratio: description: >- 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. example: 1.58 minimum: 0 title: Max Volume OI Ratio type: number Is_OTM_Contract: description: Only include contracts which are currently out of the money. example: true title: Is OTM Contract type: boolean Issue_types: description: An array of 1 or more issue types. example: - Common Stock - Index items: $ref: '#/components/schemas/Single_issue_type' title: Issue types type: array Min_DTE: description: 'The minimum days to expiry. Min: 0.' example: 1 minimum: 0 title: Min DTE type: integer Max_DTE: description: 'The maximum days to expiry. Min: 0.' example: 3 minimum: 0 title: Max DTE type: integer Flow_Alerts_Min_Ask_Percentage: description: >- The minimum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.25 maximum: 1 minimum: 0 title: Flow Alerts Min Ask Percentage type: number Flow_Alerts_Max_Ask_Percentage: description: >- The maximum ask percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.75 maximum: 1 minimum: 0 title: Flow Alerts Max Ask Percentage type: number Flow_Alerts_Min_Bid_Percentage: description: >- The minimum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.25 maximum: 1 minimum: 0 title: Flow Alerts Min Bid Percentage type: number Flow_Alerts_Max_Bid_Percentage: description: >- The maximum bid percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.75 maximum: 1 minimum: 0 title: Flow Alerts Max Bid Percentage type: number Flow_Alerts_Min_Bull_Percentage: description: >- The minimum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.5 maximum: 1 minimum: 0 title: Flow Alerts Min Bull Percentage type: number Flow_Alerts_Max_Bull_Percentage: description: >- The maximum bull percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.9 maximum: 1 minimum: 0 title: Flow Alerts Max Bull Percentage type: number Flow_Alerts_Min_Bear_Percentage: description: >- The minimum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.5 maximum: 1 minimum: 0 title: Flow Alerts Min Bear Percentage type: number Flow_Alerts_Max_Bear_Percentage: description: >- The maximum bear percentage. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1. example: 0.9 maximum: 1 minimum: 0 title: Flow Alerts Max Bear Percentage type: number Flow_Alerts_Min_Skew: description: 'The minimum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.' example: 0.3 maximum: 1 minimum: 0 title: Flow Alerts Min Skew type: number Flow_Alerts_Max_Skew: description: 'The maximum skew. Decimal proxy for percentage (0 to 1). Min: 0. Max: 1.' example: 0.7 maximum: 1 minimum: 0 title: Flow Alerts Max Skew type: number Flow_Alerts_Min_Price: description: 'The minimum price of the underlying asset. Min: 0.' example: 10.5 minimum: 0 title: Flow Alerts Min Price type: number Flow_Alerts_Max_Price: description: 'The maximum price of the underlying asset. Min: 0.' example: 500.75 minimum: 0 title: Flow Alerts Max Price type: number Flow_Alerts_Min_IV_Change: description: >- The minimum IV change. Unbounded decimal proxy for percentage (e.g., 0.01 for minimum +1% change). example: 0.01 title: Flow Alerts Min IV Change type: number Flow_Alerts_Max_IV_Change: description: >- The maximum IV change. Unbounded decimal proxy for percentage (e.g., 0.05 for maximum +5% change). example: 0.05 title: Flow Alerts Max IV Change type: number Flow_Alerts_Min_Size_Volume_Ratio: description: 'The minimum size to volume ratio. Min: 0.' example: 1.5 minimum: 0 title: Flow Alerts Min Size Volume Ratio type: number Flow_Alerts_Max_Size_Volume_Ratio: description: 'The maximum size to volume ratio. Min: 0.' example: 10 minimum: 0 title: Flow Alerts Max Size Volume Ratio type: number Flow_Alerts_Min_Spread: description: 'The minimum spread. Min: 0.' example: 0.05 minimum: 0 title: Flow Alerts Min Spread type: number Flow_Alerts_Max_Spread: description: 'The maximum spread. Min: 0.' example: 5 minimum: 0 title: Flow Alerts Max Spread type: number Min_Marketcap: description: 'The minimum marketcap. Min: 0.' example: 1000000 minimum: 0 title: Min Marketcap type: number Max_Marketcap: description: 'The maximum marketcap. Min: 0.' example: 250000000 minimum: 0 title: Max Marketcap type: number Flow_Alerts_Is_Multi_Leg: description: Boolean flag whether the transaction is a multi-leg transaction. example: true title: Flow Alerts Is Multi Leg type: boolean Flow_Alerts_Size_Greater_Than_Open_Interest: description: Only include alerts where the size is greater than the open interest. example: true title: Flow Alerts Size Greater Than Open Interest type: boolean Flow_Alerts_Volume_Greater_Than_Open_Interest: description: Only include alerts where the volume is greater than the open interest. example: true title: Flow Alerts Volume Greater Than Open Interest type: boolean MinDaysBetweenExpiryAndEarnings: description: >- 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. example: 1 title: MinDaysBetweenExpiryAndEarnings type: integer MaxDaysBetweenExpiryAndEarnings: description: >- 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. example: 6 title: MaxDaysBetweenExpiryAndEarnings type: integer NewerThan: description: >- 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). example: 1_715_083_417 title: NewerThan type: string OlderThan: description: >- 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). example: 1_715_083_417 title: OlderThan type: string Default_100_Max_200_Min_1: default: 100 description: 'How many items to return. Default: 100. Max: 200. Min: 1.' example: 10 maximum: 200 minimum: 1 title: Default 100 Max 200 Min 1 type: integer Flow_Alert: description: | Representation of a flow alert. example: data: - alert_rule: RepeatedHits all_opening_trades: false created_at: '2023-12-12T16:35:52.168Z' expiry: '2023-12-22T00:00:00.000Z' 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' properties: alert_rule: $ref: '#/components/schemas/Alert_Rule_Name' all_opening_trades: $ref: '#/components/schemas/Option_Contract_All_Opening_Trades' created_at: $ref: '#/components/schemas/General_UTC_Timestamp' delta: description: >- Size weighted delta of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number expiry: $ref: '#/components/schemas/Option_Contract_Expiry' expiry_count: $ref: '#/components/schemas/Option_Contract_Expiry_Count' gamma: description: >- Size weighted gamma of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number has_floor: $ref: '#/components/schemas/Option_Contract_Has_Floor' has_multileg: $ref: '#/components/schemas/Single_Trade_Has_Multileg' has_singleleg: $ref: '#/components/schemas/Single_Trade_Is_Single_Leg' has_sweep: $ref: '#/components/schemas/Single_Trade_Is_Sweep' issue_type: $ref: '#/components/schemas/Stock_Issue_Type' iv: description: >- Size weighted implied volatility of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number open_interest: $ref: '#/components/schemas/ToBeDone' option_chain: $ref: '#/components/schemas/Option_Contract_Symbol' price: $ref: '#/components/schemas/ToBeDone' rho: description: >- Size weighted rho of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number strike: $ref: '#/components/schemas/Option_Contract_Strike' theo: description: >- Size weighted theoretical option price of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number theta: description: >- Size weighted theta of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number ticker: $ref: '#/components/schemas/ToBeDone' total_ask_side_prem: $ref: '#/components/schemas/ToBeDone' total_bid_side_prem: $ref: '#/components/schemas/ToBeDone' total_premium: $ref: '#/components/schemas/ToBeDone' total_size: $ref: '#/components/schemas/ToBeDone' trade_count: $ref: '#/components/schemas/ToBeDone' type: $ref: '#/components/schemas/Option_Contract_Type' underlying_price: $ref: '#/components/schemas/ToBeDone' vega: description: >- Size weighted vega of all transactions that make up the flow alert. Null when unavailable. format: double nullable: true type: number volume: $ref: '#/components/schemas/ToBeDone' volume_oi_ratio: $ref: '#/components/schemas/ToBeDone' title: Flow Alert type: object Authentication_Error: description: >- Returned with HTTP 401 when a request carries no API token, or carries one the API cannot use. The response also carries a `WWW-Authenticate` header with the `Bearer` challenge. Branch on `reason` rather than on `message`, whose wording can change. example: code: authentication_required documentation_url: https://api.unusualwhales.com/docs expected_format: uuid message: >- The API token provided is not in the expected format. Unusual Whales API tokens are UUIDs, such as 123e4567-e89b-12d3-a456-426614174000. reason: malformed_token request_id: GNI_YTC1CRnw2LACGBvE retryable: false support_email: dev@unusualwhales.com token_url: https://unusualwhales.com/dashboard/api properties: code: description: Always `authentication_required`. enum: - authentication_required type: string documentation_url: description: Where to read this API documentation. type: string expected_format: description: >- Present only when `reason` is `malformed_token`. The format the token must take. enum: - uuid type: string message: description: A plain description of the failure, written for a person. type: string reason: description: >- Which authentication failure occurred. `missing_token` means the request carried no token. `malformed_token` means a token was supplied but is not a UUID. `unrecognized_token` means the token is a UUID that no active token matches, which happens after a token is revoked or regenerated, or when it belongs to a different account. enum: - missing_token - malformed_token - unrecognized_token type: string request_id: description: >- Identifies this request in Unusual Whales logs. Quote it when contacting support. It matches the `x-request-id` response header, and is absent when no request id was assigned. type: string retryable: description: >- Always `false`. Replaying the same request unchanged returns the same error. Retrying with a corrected token can succeed. enum: - false type: boolean support_email: description: Where to send questions about API access. type: string token_url: description: Where to create and manage API tokens. type: string title: Authentication Error type: object Forbidden_Error: description: >- Returned with HTTP 403 when the API token is valid and recognized, but is not entitled to what the request asked for. Branch on `code`, which names the entitlement that is missing; `message` is written for a person and its wording can change. Unlike a 401 this response carries no `WWW-Authenticate` header, because presenting different credentials for the same token does not change the outcome. Only `code` and `message` are guaranteed. The remaining fields are sent by some checks and not others, so treat every one of them as optional. A 403 whose body is not JSON, or is JSON without a `code` field, did not come from this API. Those are produced by Cloudflare in front of the API, or by a proxy on the caller's own network, and neither says anything about the token or the subscription. example: code: missing_access documentation_url: https://api.unusualwhales.com/docs message: >- The API token provided is valid but is not permitted to access this route. reason: route_not_permitted request_id: GNI_YTC1CRnw2LACGBvE retryable: false support_email: dev@unusualwhales.com token_url: https://unusualwhales.com/dashboard/api properties: code: description: >- Which entitlement is missing. `missing_access` means the token is restricted to a set of routes that excludes the requested one. `historic_data_access_missing` means a date in the request predates the earliest date the token may query. `advanced_tier_required`, `futures_access_required`, `politics_scope_required` and `volatility_scope_required` each mean the endpoint needs a subscription tier or data add-on the account does not have. `admin_required` means the endpoint is internal to Unusual Whales. enum: - missing_access - historic_data_access_missing - advanced_tier_required - futures_access_required - politics_scope_required - volatility_scope_required - admin_required type: string documentation_url: description: Where to read this API documentation. type: string message: description: >- A plain description of what is missing and how to obtain it, written for a person. Do not branch on this string. type: string reason: description: >- Present only when `code` is `missing_access`. Narrows the cause within that code. enum: - route_not_permitted type: string request_id: description: >- Identifies this request in Unusual Whales logs. Quote it when contacting support. It matches the `x-request-id` response header, and is absent when no request id was assigned. type: string retryable: description: >- When present, always `false`. Replaying the same request unchanged returns the same error. Changing the request, the token, or the subscription can succeed. enum: - false type: boolean support_email: description: Where to send questions about API access. type: string token_url: description: Where to create and manage API tokens. type: string required: - code - message title: Forbidden Error type: object Error_Message: description: A json object containing information on the error cause. example: msg: >- Invalid path input: MSFT12 (valid example: AAPL) - Invalid query input(s): date=2023-02-140 (valid example: date=2024-01-18) path: /api/darkpool/MSFT12 query: date=2023-02-140 url: localhost:4000/api/darkpool/MSFT12?date=2023-02-140 properties: msg: description: An error message containing information about the faulty input. type: string path: description: The URL path segment. type: string query: description: The URL query segment. type: string url: description: The full URL causing the error. type: string title: Error Message type: object Error_Message_on_an_internal_server_error.: description: >- A plain message informing, that an internal server error occured. In this case please send a mail with the full URL that caused the issue to support@unusualwhales.com. example: Something went wrong title: Error Message on an internal server error. type: string Flow_alert_rule: description: '' enum: - FloorTradeSmallCap - FloorTradeMidCap - RepeatedHits - RepeatedHitsAscendingFill - RepeatedHitsDescendingFill - FloorTradeLargeCap - OtmEarningsFloor - LowHistoricVolumeFloor - SweepsFollowedByFloor example: RepeatedHits title: Flow alert rule type: string Single_issue_type: description: A singular issue type. enum: - Common Stock - ETF - Index - ADR example: Common Stock title: Single issue type type: string Alert_Rule_Name: description: The name of the alert rule. example: RepeatedHits title: Alert Rule Name type: string Option_Contract_All_Opening_Trades: description: '' example: false title: Option Contract All Opening Trades type: boolean General_UTC_Timestamp: description: A UTC timestamp. example: '2023-12-12T16:35:52.168Z' title: General UTC Timestamp type: string Option_Contract_Expiry: description: The contract expiry date in ISO format. example: '2023-12-22T00:00:00.000Z' title: Option Contract Expiry type: string Option_Contract_Expiry_Count: description: >- The amount of expiries belonging to the trade. This is only greater than 1 if it is a multileg trade. example: 2 title: Option Contract Expiry Count type: integer Option_Contract_Has_Floor: description: '' example: false title: Option Contract Has Floor type: boolean Single_Trade_Has_Multileg: description: Whether the trade is a multileg trade. example: false title: Single Trade Has Multileg type: boolean Single_Trade_Is_Single_Leg: description: Whether the trade is a singleleg trade. example: true title: Single Trade Is Single Leg type: boolean Single_Trade_Is_Sweep: description: Whether the trade is a sweep. example: true title: Single Trade Is Sweep type: boolean Stock_Issue_Type: description: The issue type of the ticker. enum: - Common Stock - ETF - Index - ADR example: Common Stock title: Stock Issue Type type: string ToBeDone: description: '' title: ToBeDone Option_Contract_Symbol: description: > The option symbol of the contract. You can use the following regex to extract underlying ticker, option type, expiry & strike: `^(?[\w]*)(?(\d{2})(\d{2})(\d{2}))(?[PC])(?\d{8})$` Keep in mind that the strike needs to be multiplied by 1,000. title: Option Contract Symbol type: string Option_Contract_Strike: description: The contract strike. example: '375' title: Option Contract Strike type: string Option_Contract_Type: description: The contract type. enum: - call - put example: call title: Option Contract Type type: string securitySchemes: authorization: scheme: bearer type: http ````