> ## 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 # Portfolio ticker > Returns the open positions, closed-trade results and recent trades of the user in one ticker and its options across all accounts, with the next earnings and dividend dates. The range is limited to three years. Returns only the Trading Journal accounts of the user that owns the API token. Every active API token can call this endpoint. Accounts are linked in the Trading Journal on unusualwhales.com, which needs a Max or professional plan, so a token whose owner has linked no accounts gets an empty result. ## OpenAPI ````yaml /openapi.yaml get /api/portfolio/ticker/{ticker} 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: 160K daily requests, 5 concurrent requests, 2-year lookback, and commercial use included. Annual plan available at $7,500/yr (2 months free) with 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 10 concurrent requests. [Start building →](https://unusualwhales.com/checkout?plan=enterprise_startup_kafka&interval=monthly) ## CBOE Index Prices For CBOE index tickers such as SPX or VIX the index price is returned as `null` and the row is marked `missing_periscope`. If the request filters with `min_underlying_price`, `max_underlying_price`, `min_stock_price`, `max_stock_price`, `min_diff`, `max_diff`, `min_implied_move`, `max_implied_move`, `min_return_on_capital`, `max_return_on_capital`, `min_return_on_capital_perc` or `max_return_on_capital_perc`, rows for these index tickers are left out of the response. CBOE index prices require provisioned access and CBOE approval. Contact oskar@unusualwhales.com, enterprise@unusualwhales.com or nastja.petrovic@unusualwhales.com to request access. This applies to every REST endpoint that can return an index price, not only the ones whose description repeats it. ## 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.11.12 - Congress trade endpoints return pages of trades. Each response adds `page`, the page returned, and `total_pages`, the number of pages for the given filters and `limit`. The maximum `limit` is 500 instead of 200. - [`/congress/recent-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.CongressController.congress_recent_trades) and [`/congress/late-reports`](https://api.unusualwhales.com/docs/operations/PublicApi.CongressController.congress_late_reports) add the `page` parameter. - [`/congress/congress-trader`](https://api.unusualwhales.com/docs/operations/PublicApi.CongressController.congress_trader) already had `page`. # 2026.11.11 - Futures prices come formatted as CME quotes them, for example 106'025 for ZN and 425'2 for corn, with the fractions CME's security definition lists for the contract. `main_fraction` and `sub_fraction` are those fractions and are null when the prices show decimals. - [`/futures/flow`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.flow) adds `price_display`, `nbbo_bid_display`, `nbbo_ask_display`, `quote_bid_display`, `quote_ask_display`, `main_fraction` and `sub_fraction`. - [`/futures/{contract}/trades`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.trades) adds the same fields and `tick_size`. # 2026.11.09 - Added Trading Journal endpoints that return the Trading Journal accounts of the user that owns the API token. Every active API token can call them. Accounts are linked in the Trading Journal on unusualwhales.com, which needs a Max or professional plan, so a token whose owner has linked no accounts gets empty results. `account` limits a request to one account by `id` or exact `name`. - [`/portfolio/accounts`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.accounts): accounts with broker, sync status, last date with data and latest total value. - [`/portfolio/holdings`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.holdings): open positions with weights, unrealized P&L, sectors and options risk. - [`/portfolio/performance`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.performance): time-weighted returns, P&L, monthly returns and risk metrics over `range`. - [`/portfolio/trades`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.trades): closed trades between `from` and `to`, filtered by `ticker` and `kind` and sorted by `sort`. - [`/portfolio/edge`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.edge): win rate, profit factor and expectancy overall and per type, side, ticker, strategy, holding period, entry condition and hour. - [`/portfolio/ticker/:ticker`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.ticker): positions and trade results in one ticker. - [`/portfolio/catalysts`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.catalysts): earnings and ex-dividend dates in the next 30 days for holdings. - [`/portfolio/rank`](https://api.unusualwhales.com/docs/operations/PublicApi.PortfolioController.rank): Trade Rank per period. - Added MCP tools `get_my_accounts`, `get_my_holdings`, `get_my_performance`, `get_my_trades`, `get_my_edge`, `get_my_ticker`, `get_my_catalysts` and `get_my_rank` for the data of these endpoints. - Added `next_earnings_confirmed` to [`/stock/{ticker}/info`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.info). It is true if the company confirmed `next_earnings_date` and false if the date is an estimate. # 2026.11.04 - [`/stock/{ticker}/option-contracts`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionContractController.option_contracts) returns `delta`, `gamma`, `theta`, `vega` and `rho` as numbers instead of strings, for every `date`. # 2026.11.03 - `exchange` in [`/stock-directory/ticker-exchanges`](https://api.unusualwhales.com/docs/operations/PublicApi.StockDirectoryController.ticker_exchanges) can be `texas_stock_exchange` for tickers whose primary listing is on the Texas Stock Exchange. - Added the `@equity` scope to the query language, also spelled `@equities`. It selects common stocks and ADRs, the same as `@stock+adr`, while `@stock` still selects common stocks only. It works in: - `input` on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config) - the `query` parameter of [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) - the `query` parameter of [`/screener/stocks`](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.stock_screener) # 2026.11.02 - Added cursor pagination to [`/insider/transactions`](https://api.unusualwhales.com/docs/operations/PublicApi.InsiderController.transactions). Each response includes `cursor.next`, which is null on the last page. Pass it as `cursor` to fetch the next page. `page` is deprecated on this endpoint and will be removed. - Added `min_volume_avg_7_day_volume_ratio`, `max_volume_avg_7_day_volume_ratio`, `min_volume_avg_30_day_volume_ratio` and `max_volume_avg_30_day_volume_ratio` to three endpoints. They filter on the contract's volume for the day divided by the underlying's average daily option volume over the previous 7 or 30 trading days, calls plus puts, as of the row's trading date. For example, `min_volume_avg_30_day_volume_ratio=0.5` returns contracts whose volume is at least half of the underlying's average daily option volume. A row does not match while the underlying has no average volume for that date. - [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) - [`/option-trades/flow-alerts`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alerts) - [`/screener/option-contracts`](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.contract_screener) - Added `volume_avg_7_day_volume_ratio` and `volume_avg_30_day_volume_ratio` to the query language for the `option_trade` alert type, to [`/alerts/query/grammar?target=option_trade`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.dsl_grammar) and to the `query` parameter of [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index). Option trade alert configurations on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config) accept the same `min_` and `max_` filters. - Added [`/predictions/ticker/:ticker`](https://api.unusualwhales.com/docs/operations/PublicApi.PredictionController.ticker), the open prediction markets about a stock ticker, such as "Will Apple (AAPL) close above $270?" or "Apple Vision Pro 2 released before 2027?" for AAPL. Each market has an `event_type` (`price`, `market_cap`, `earnings`, `product_release`, `corporate` or `other`), and `event_types=price,earnings` filters on it. `view=events` returns one row per event with the number of its matching markets, and `include_closed=true` includes closed markets. - Added `avg30d_volume`, with the aliases `avg30d_stock_volume` and `avg30d_share_volume`, to the query language in `input` on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config) for the `option_trade`, `option_contract`, `option_contract_interval`, `flow_alert` and `multi_leg_trade` alert types, and to [`/alerts/query/grammar`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.dsl_grammar) for these targets. It is the 30-day average daily stock volume of the underlying in shares, rounded down and fixed for the trade's trading date, from the same source as `avg30d_volume` on `stock_trade`. It works in comparisons and arithmetic, e.g. `where abs(delta_impact) * 20 > avg30d_stock_volume`. The `query` parameter of [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) accepts it as well. A comparison with it does not match while the underlying has no 30-day average volume for the trading date. # 2026.11.01 - A `limit` that is not a whole number from 1 to 500 now returns HTTP 400 with the code `invalid_query_parameters` on three endpoints. These requests used to return a different number of rows than requested, or an HTTP 500. On Flow Alerts the default is 50 and the maximum is 500, which is what the endpoint already served. - [`/option-trades/flow-alerts`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alerts) - [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) - [`/screener/option-contracts`](https://api.unusualwhales.com/docs/operations/PublicApi.ScreenerController.contract_screener) # 2026.10.31 - Added [`/sec-filings`](https://api.unusualwhales.com/docs/operations/PublicApi.SecFilingsController.index), the REST counterpart of the `sec:filings` websocket channel. It returns SEC EDGAR filings newest first and filters by `ticker`, `form`, `start_date` and `end_date`. Pages use a cursor: pass `next_cursor` from a response as `cursor` to get the next page. - Added `ticker_open_int`, alias `ticker_oi`, to the query language in `input` on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config) for the `option_trade`, `option_contract`, `option_contract_interval`, `flow_alert` and `multi_leg_trade` alert types, and to [`/alerts/query/grammar`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.dsl_grammar) for these targets. It is the open interest of every option contract on the underlying, calls plus puts, from the latest published open interest. This is `call_open_interest` plus `put_open_interest` from [`/stock/:ticker/options-volume`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.options_volume). It works in comparisons and arithmetic, e.g. `where ticker_open_int < 50000` or `where size > ticker_open_int * 0.02`. A comparison with it does not match while the underlying has no published open interest. - Added `ticker_avg_7_day_volume` (alias `ticker_avg_7d_vol`) and `ticker_avg_30_day_volume` (alias `ticker_avg_30d_vol`) to the query language for the `option_trade` alert type and to [`/alerts/query/grammar?target=option_trade`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.dsl_grammar). They are the average daily option volume of the underlying over the previous 7 and 30 trading days, calls plus puts, from the latest open interest update. - The `query` parameter of [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) accepts `ticker_open_int`, `ticker_avg_7_day_volume` and `ticker_avg_30_day_volume`. Each trade carries the values of its underlying at the time it was published, so a comparison with them does not match trades published before this release. - The Kafka topic `all-option-trades` carries `ticker_open_interest`, `ticker_avg_7_day_volume` and `ticker_avg_30_day_volume` with the same values, each absent while unknown. `ticker-oi-stats` carries `avg_30_day_call_volume` and `avg_30_day_put_volume`. # 2026.10.30 - The `x-uw-req-per-minute-remaining` and `x-uw-req-per-minute-reset` response headers are deprecated and will be removed after 2026-12-31. They always hold `1000000` and `60000` and do not reflect a limit, because the API has no per-minute cap. The limits that apply are described under [Rate limits](https://api.unusualwhales.com/docs/conventions#rate-limits). - With `include_agg_trades=true`, [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) now returns a rolled up transaction for the `report_flag[]` values `intermarket_sweep`, `cross_trade` and `futures_floor` when any of the transactions it rolls up carries that flag, and leaves those transactions out of the response. Before, every one of them had to carry the flag, so a rolled up transaction that mixed sweeps with other transactions did not match `report_flag[]=intermarket_sweep` and its sweeps were returned one by one. For `normal`, a rolled up transaction matches when any of its trade codes is a `trade_codes[]` value other than a floor, cross or sweep code. The MCP tool `get_option_trades` matches rolled up transactions the same way when `add_agg_trades` is true. # 2026.10.29 - Added `min_created_at` and `max_created_at` to [`/crypto/list_tokens`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.list_tokens). Both take an RFC 3339 time and include tokens created exactly at that time. Tokens whose `created_at` is `null` are left out when either filter is set. # 2026.10.28 - Added `created_at` to [`/crypto/list_tokens`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.list_tokens) and [`/crypto/token/:token`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.get_token), the time the token was created on chain in RFC 3339. It is `null` when the creation time is not known. - Added `is_low_quality` to [`/crypto/list_tokens`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.list_tokens) and [`/crypto/token/:token`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.get_token). It is `true` for a token with fewer than 50 holders, a market cap of zero, or a market cap above $10,000,000 per holder, which is often a fake or spam token. `/crypto/list_tokens` takes `hide_low_quality=true` to leave these tokens out. - Added `is_large_swap` to [`/crypto/trades`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.list_trades). It is `true` for a swap of $50,000 or more in USD, and always `false` for liquidity adds and removes. # 2026.10.27 - [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index) and the MCP tool `get_option_trades` now support ordering by premium and size. Set `order` to `premium` or `size`, and `order_direction` to `asc` or `desc`. # 2026.10.26 - [`/crypto/token/:token`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.get_token) and [`/crypto/list_tokens`](https://api.unusualwhales.com/docs/operations/PublicApi.CryptoController.list_tokens) now compute `price`, `price_change_24h` and `volume_24h` from every pool the token trades in, not only its USDT pool. `volume_24h` is in USD, and `price_change_24h` is a percent change over the last 24 hours, or `null` when the price 24 hours ago is unknown. On `/crypto/list_tokens`, `market_cap` and `fdv` are now the circulating and total supply times `price`, as on `/crypto/token/:token`, and tokens that traded in the last 24 hours are listed even without a USDT pool. # 2026.10.24 - Added `min_capped_pnl` and `max_capped_pnl` to [`/option-trades/multi-leg`](https://api.unusualwhales.com/docs/operations/PublicApi.MultiLegController.index). They filter on the larger absolute value of `max_loss` and `max_profit`, so a long and a short strangle of the same size match the same filter. Both accept `abs()` like the other multi-leg filters, e.g. `min_capped_pnl=abs(100000)` is the same as `min_capped_pnl=100000`. Multi-expiration strategies such as calendars and diagonals have no computed `max_loss` or `max_profit` and are excluded. The MCP tool `get_multi_trades` accepts both filters. # 2026.10.23 - Added the `call_spread_collar` and `put_spread_collar` strategies to [`/option-trades/multi-leg`](https://api.unusualwhales.com/docs/operations/PublicApi.MultiLegController.index), in the `strategy` field and the `strategy` filter. A short put with a long call spread is a `call_spread_collar`, and a long put spread with a short call is a `put_spread_collar`. These three-leg structures were returned as `risk_reversal` before, and earlier trades keep that strategy. - Stock-tied multi-leg trades (trade codes `tlat`, `tlet`, `tlct` and `tlft`) are now grouped into strategies on [`/option-trades/multi-leg`](https://api.unusualwhales.com/docs/operations/PublicApi.MultiLegController.index) when two or more option legs trade together. Their `code` field holds the stock-tied trade code. - Added `min_notional` to `futures_print` alert configurations on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config), the smallest notional in USD a print must reach, price × size × multiplier. It combines with `min_size`, and one of the two is required. A print of a contract without a usable multiplier carries no notional and never satisfies a notional floor. Triggered alerts carry `notional` and `multiplier` in `meta`. Rates and grains notionals use the corrected multipliers from the first security definition sync after the 2026-10-21 release. - Added the `futures_sweep` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config): a CME match event that filled several price levels on one contract, `"contract": "NQZ6"`, or on every contract of a product, `"product": "NQ"`. `min_levels` is 2 by default and at least 2, `min_size` and `min_notional` are optional floors, `side` limits it to `buy`, `sell` or `none` and `contracts` to `outrights`, `spreads` or `all`, outrights by default. An event alerts each configuration once, at most once per minute per configuration and scope, and the alert is never paused. Triggered alerts carry `side`, `levels`, `size`, `prints`, `low`, `high`, `notional` and `executed_at` in `meta`. Needs the Advanced API tier or the futures add-on. - Added the `futures_block` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config): a new CME block trade on one contract, `"contract": "ESZ6"`, or on every contract of a product, `"product": "ES"`, with `min_qty` and `min_notional` as optional floors. Multi-leg blocks are left out unless `"multi_leg": true`, and they carry no notional, so a notional floor never matches one. Updates and deletes of a block never alert. Each block alerts once, at most once per minute per configuration and scope, and the alert is never paused. Triggered alerts carry `price`, `qty`, `notional`, `legs`, `quote_bid`, `quote_ask`, `reported_at` and `trade_date` in `meta`. Needs the Advanced API tier or the futures add-on. - Added the `futures_roll` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config): the lead contract of a product changed, for one product, `"product": "ES"`, or for every product, `"product": "all"`. The lead is the contract with the highest 5-day rolling volume, so it can flip back, which alerts again. One alert per roll per configuration, never paused. Triggered alerts carry `product`, `from`, `to` and `trading_date` in `meta`. Needs the Advanced API tier or the futures add-on. - Added the `futures_expiry` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config): one contract, `"contract": "ESZ6"`, or the nearest unexpired contract of a product, `"product": "ES"`. `days_before` lists the days before expiry that alert, 1, 3 and 7 by default and each once per contract, with a day the check missed alerting on its next run, and `"settlement": true` also alerts once the final settlement price is published. Checked hourly. Triggered alerts carry `expiry`, `trigger`, `days` and `settlement` in `meta`. Needs the Advanced API tier or the futures add-on. - The alert listing and configuration endpoints filter all futures alert types with `noti_types[]=futures_price,futures_print,futures_sweep,futures_block,futures_roll,futures_expiry`. # 2026.10.20 - Added `2m` and `3m` to `candle_size` on [`/stock/:ticker/ohlc/:candle_size`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.ohlc). The MCP tools `get_ticker_candles_by_range`, `get_ticker_indicator_series` and `get_ticker_indicator_events` accept the same values in `range`. - Added `repeat` and `rearm_ticks` to `price_target` and `futures_price` alert configurations on [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config). With `"repeat": true` the configuration is not paused after a trigger. Each target re-arms once the price has come back inside it by `rearm_ticks` ticks, 2 by default and at least 1, never less than 0.1% of the target, and the next crossing triggers again, at most once a minute per target. After a restart, a target the price already sits beyond waits for the price to come back inside before it can trigger. - Added the `futures_print` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config). The `config` names one contract, `"contract": "ESZ6"`, or a product, `"product": "ES"`, which matches every contract of the product, plus `min_size` in contracts. `side` limits it to `buy`, `sell` or `none` prints and `contracts` to `outrights`, `spreads` or `all`, outrights by default. The alert fires on every matching print, at most once per minute per configuration and scope, and is never paused. Triggered alerts carry `price`, `size` and `side` in `meta`. Like `futures_price`, it needs the Advanced API tier or the futures add-on. - Futures display factors are versioned per contract symbol, because CME reuses a `security_id` for a new contract once the previous one expires. - [`/futures/display_factors`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.display_factors) returns the current definition of each `security_id`. It takes `history=true` to include closed definitions and `after_symbol` next to `after_id` as the cursor. - [`/futures/display_factors/:security_id`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.display_factor) returns the current definition and takes `symbol` for another one. - Added [`/futures/display_factors/:security_id/history`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.display_factor_history), every definition of a `security_id`, oldest first. - Display factor items carry `valid_from` and `valid_to`. `valid_to` is null on the current definition. - [`/futures/flow`](https://api.unusualwhales.com/docs/operations/PublicApi.FuturesController.flow) prints carry `event_ts_ns`, `event_levels` and `event_size` once their CME match event is complete, and `sweeps_only=true` returns only prints of events that filled at least two price levels. # 2026.10.19 - Starter-only accounts cannot create GEX, futures-price or prediction alerts through [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config). Independent qualifying subscriptions or permissions retain access. - Request-limit errors now describe both daily and billing-month resets instead of assuming every allowance resets daily. # 2026.10.16 - [Full Tape](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.full_tape) now returns HTTP 403 for dates more than 30 calendar days old while an API subscription has status `trialing`. # 2026.10.15 - Added `combos` to [`/predictions/user/:user_id`](https://api.unusualwhales.com/docs/operations/PublicApi.PredictionController.user). It values the user's Polymarket Combos, which `positions` leaves out: `count`, `settled_count` and `pnl`, the PnL in USD before fees. Combos that have not settled yet count at cost. It is null for users with more than 20,000 Combo positions. - Added the `futures_price` alert type to [`POST /alerts/configuration`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.create_config). The `config` names either one CME futures contract, `"contract": "ESZ6"`, or a product, `"product": "ES"`, plus `price_target_upper`, `price_target_lower` or both, in the contract's display price. A product alert follows the product's current lead contract, which is the outright contract with the highest 5-day rolling volume, so it rolls on its own. The alert fires on the first print at or through a target and the configuration is then paused. Triggered alerts carry the product or contract in `symbol` and the contract that traded in `meta.sym`, and `noti_types[]=futures_price` selects them on [`/alerts`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.alerts). # 2026.10.14 - Added `min_profit`, `max_profit`, `min_loss` and `max_loss` to [`/option-trades/multi-leg`](https://api.unusualwhales.com/docs/operations/PublicApi.MultiLegController.index). They filter on the `max_profit` and `max_loss` fields and accept `abs()`. `max_loss` is negative, so `min_loss=abs(100000)` returns strategies that can lose at least $100,000. Strategies with an unbounded profit or loss are excluded by the matching filter. # 2026.10.13 - Added the `query` parameter to [`/option-trades`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.index). It takes a Query language expression, such as `where premium > 100k and strike > spot`, and combines it with the other filters using `and`. The fields, operators and functions are listed by [`/alerts/query/grammar?target=option_trade`](https://api.unusualwhales.com/docs/operations/PublicApi.AlertsController.dsl_grammar). - [`/option-trades/flow-alerts`](https://api.unusualwhales.com/docs/operations/PublicApi.OptionTradeController.flow_alerts): Default lookback is 7 days without a specified `newer_than`. - [`/predictions/user/:user_id`](https://api.unusualwhales.com/docs/operations/PublicApi.PredictionController.user) now returns at most 20,000 `positions`, the ones with the highest `total_invested_usd`. The new `positions_truncated` field is true when the user has more positions than that. # 2026.10.12 - Added `earnings_report_time` to [`/stock/:ticker/volatility/context`](https://api.unusualwhales.com/docs/operations/PublicApi.VolatilityController.context). It is `premarket`, `postmarket` or `unknown`, or null when no report is scheduled or its time is not recorded. `expiry.earnings_in_expiry` is now false when the report is `postmarket` on the expiry date. - Whale Bundle Basic monthly and annual plans now include unlimited API requests. - Added `chart` and `chart_member` to each `rev_breakdown` row of [`/stock/:ticker/fundamental-breakdown`](https://api.unusualwhales.com/docs/operations/PublicApi.FundamentalController.show). A filing often reports the same revenue in several breakdowns, and subtotals next to their parts. `chart` is `product` or `region` for the rows of the one breakdown picked for that chart, whose members add up to the report's revenue where possible, and `null` for every other row. With `period=all`, each period of a report has its own chart rows. `chart_member` is the member to label the row with. # 2026.10.09 - Added endpoints to manage the stock and option watchlists of the user. These are the same watchlists as on unusualwhales.com, so changes made through the API show up on the website. - [`GET /watchlists/stocks`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_index) and [`GET /watchlists/options`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.option_index) list the watchlists. - [`POST /watchlists/stocks`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_create) and [`POST /watchlists/options`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.option_create) create a watchlist. - [`PUT /watchlists/stocks/:id`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_update) and [`PUT /watchlists/options/:id`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.option_update) replace the name, contents and color of a watchlist. WARNING: Tickers or option symbols missing from the request are removed from the watchlist. - [`POST /watchlists/stocks/:id/add-tickers`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_add_tickers) and [`POST /watchlists/stocks/:id/remove-tickers`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_remove_tickers) add or remove tickers on a stock watchlist and keep the other tickers. - [`DELETE /watchlists/stocks/:id`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.stock_delete) and [`DELETE /watchlists/options/:id`](https://api.unusualwhales.com/docs/operations/PublicApi.WatchlistController.option_delete) delete a watchlist. # 2026.10.08 - Added the `period` query parameter to [`/stock/:ticker/fundamental-breakdown`](https://api.unusualwhales.com/docs/operations/PublicApi.FundamentalController.show). `quarter`, the default, returns the quarterly `rev_breakdown` rows and the rows without a period, plus the 12-month rows of `annual_only` tickers. `annual` returns only 12-month rows, including breakdowns that a company reports only in its annual report. `all` returns every row. - Added `period_months` to each `rev_breakdown` row of the same endpoint. It is the number of months the value covers, such as 3 for a quarter and 12 for a full fiscal year. `null` marks a count at a point in time, such as the number of stores, or a row stored before this field existed. - The `rev_group` documentation now lists `country` and `continent`, which the endpoint already returned. # 2026.09.30 - Added FLEX option endpoints. FLEX option data always lags by one trading day: - [`/flex-options`](https://api.unusualwhales.com/docs/operations/PublicApi.FlexOptionsController.contracts) returns the FLEX option contracts of a date with their open interest and mark, next to the values of the previous trading day. - [`/flex-options/market`](https://api.unusualwhales.com/docs/operations/PublicApi.FlexOptionsController.market) returns the market-wide FLEX open interest per day and the FLEX open interest per ticker on a date. - [`/flex-options/chain/:chain`](https://api.unusualwhales.com/docs/operations/PublicApi.FlexOptionsController.chain) returns the daily history of one FLEX option contract. - [`/flex-options/:ticker`](https://api.unusualwhales.com/docs/operations/PublicApi.FlexOptionsController.ticker) returns the daily FLEX open interest history of a ticker. # 2026.09.29 - Added new [SEC filing websocket channels](https://api.unusualwhales.com/docs/websocket/sec-filings): `sec:filings` (every filing), `sec:insider_trades` (insider trades, aggregated per filing and transaction type), `sec:13f_alerts` and `sec:13f_filings` (13F reports), `sec:13dg_filings` (Schedule 13D and 13G), `sec:company_reports` (10-Q, 10-K, 20-F and 40-F financial statements) and `sec:497_filings` (Rule 497 prospectuses). Each channel streams one message type of the Kafka topic `sec-filings`, with the same fields as the Kafka message. The channels cover every ticker at once and have no per-ticker variant. # 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`](https://api.unusualwhales.com/docs/operations/PublicApi.EtfController.in_outflow) # 2024.10.15 - Added institutional latest filings endpoint [`/institution/latest_filings`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.latest_filings) - Added institutional ownership endpoint [`/institution/:ticker/ownership`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.ownership) # 2024.10.14 - Added 2 new fields: `days_of_oi_increases` & `days_of_vol_greater_than_oi` to [`/market/oi-change`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.activity) # 2024.10.09 - Added institutional list endpoint [`institutions`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.list) - Added institutional holdings endpoint [`/institution/:name/holdings`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.holdings) - Added institutional sector exposure endpoint [`/institution/:name/sectors`](https://api.unusualwhales.com/docs/operations/PublicApi.InstitutionController.sectors) # 2024.08.01 - Added new flow per strike intraday endpoint [`/stock/:ticker/flow-per-strike-intraday`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.flow_per_strike_intraday) # 2024.07.11 - Added new correlation endpoint [`/market/correlations?tickers=SPY,QQQ,JPM,BAC`](https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.correlations) # 2024.05.30 - Added the ability to filter [`/darkpool/:ticker`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.spot_exposures_one_minute) and [`/stock/:ticker/spot-exposures/strike`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.last_stock_state) to retrieve the last stock price & volume - Added endpoint [`/stock/:ticker/volatility/realized`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/PublicApi.MarketController.etf_tide) # 2024.05.01 - Added endpoint [`/stock/:ticker/spot-exposures/strike`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.greek_exposure_by_strike) - Added endpoint [`/stock/:ticker/greek-exposure/expiry`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.greek_exposure_by_expiry) - Added endpoint [`/stock/:ticker/greek-exposure/strike-expiry`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.greek_exposure_by_strike_expiry) # 2024.03.28 - Fixed field name volatility -> risk_reversal for endpoint [`/stock/:ticker/historical_risk_reversal_skew`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.historical_risk_reversal_skew) # 2024.03.26 - Added endpoint [`/stock/:ticker/greeks`](https://api.unusualwhales.com/docs/operations/PublicApi.TickerController.greeks) - Added endpoint [`/stock/:ticker/historical_risk_reversal_skew`](https://api.unusualwhales.com/docs/operations/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`](https://api.unusualwhales.com/docs/operations/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/portfolio/ticker/{ticker}: get: tags: - portfolio summary: Portfolio ticker description: > Returns the open positions, closed-trade results and recent trades of the user in one ticker and its options across all accounts, with the next earnings and dividend dates. The range is limited to three years. Returns only the Trading Journal accounts of the user that owns the API token. Every active API token can call this endpoint. Accounts are linked in the Trading Journal on unusualwhales.com, which needs a Max or professional plan, so a token whose owner has linked no accounts gets an empty result. operationId: PublicApi.PortfolioController.ticker parameters: - description: The ticker, for example `NVDA`. in: path name: ticker required: true schema: type: string - description: >- Include trades closed on or after this date (YYYY-MM-DD, ET). Defaults to January 1 of the current year. in: query name: from required: false schema: format: date type: string - description: >- Include trades closed on or before this date (YYYY-MM-DD, ET). Defaults to today. in: query name: to required: false schema: format: date type: string - description: The number of rows to return. in: query name: limit required: false schema: default: 25 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/Portfolio_ticker' description: The ticker '400': content: application/json: schema: $ref: '#/components/schemas/Error_Message' description: Invalid parameters '401': content: application/json: schema: $ref: '#/components/schemas/Authentication_Error' description: Unauthorized '402': content: application/json: schema: $ref: '#/components/schemas/Payment_Required_Error' description: Payment Required '403': content: application/json: schema: $ref: '#/components/schemas/Forbidden_Error' description: Forbidden '500': content: text/plain: schema: $ref: >- #/components/schemas/Error_Message_on_an_internal_server_error. description: Internal Server Error callbacks: {} components: schemas: Portfolio_ticker: description: The trades and positions of the user in one ticker across all accounts. example: data: summary: pnl: 5120 trades: 31 win_rate: 0.65 ticker: NVDA properties: data: properties: by_hold: items: description: >- Closed-trade results of one group. Amounts are in USD and rates are fractions. properties: avg_loss: nullable: true type: number avg_win: nullable: true type: number expectancy: description: '`pnl / trades`, the average P&L per trade.' nullable: true type: number gross_loss: description: The sum of losing trades, zero or negative. type: number gross_profit: type: number key: description: The group, such as `calls`, `NVDA` or `0DTE`. type: string losers: type: integer pnl: description: Realized P&L in USD. type: number profit_factor: description: >- `gross_profit / abs(gross_loss)`. Null without losing trades. nullable: true type: number trades: type: integer win_rate: description: >- `winners / (winners + losers)`. Trades with zero P&L are left out. Null without decided trades. nullable: true type: number winners: type: integer type: object type: array by_side: items: description: >- Closed-trade results of one group. Amounts are in USD and rates are fractions. properties: avg_loss: nullable: true type: number avg_win: nullable: true type: number expectancy: description: '`pnl / trades`, the average P&L per trade.' nullable: true type: number gross_loss: description: The sum of losing trades, zero or negative. type: number gross_profit: type: number key: description: The group, such as `calls`, `NVDA` or `0DTE`. type: string losers: type: integer pnl: description: Realized P&L in USD. type: number profit_factor: description: >- `gross_profit / abs(gross_loss)`. Null without losing trades. nullable: true type: number trades: type: integer win_rate: description: >- `winners / (winners + losers)`. Trades with zero P&L are left out. Null without decided trades. nullable: true type: number winners: type: integer type: object type: array by_strategy: items: description: >- Closed-trade results of one group. Amounts are in USD and rates are fractions. properties: avg_loss: nullable: true type: number avg_win: nullable: true type: number expectancy: description: '`pnl / trades`, the average P&L per trade.' nullable: true type: number gross_loss: description: The sum of losing trades, zero or negative. type: number gross_profit: type: number key: description: The group, such as `calls`, `NVDA` or `0DTE`. type: string losers: type: integer pnl: description: Realized P&L in USD. type: number profit_factor: description: >- `gross_profit / abs(gross_loss)`. Null without losing trades. nullable: true type: number trades: type: integer win_rate: description: >- `winners / (winners + losers)`. Trades with zero P&L are left out. Null without decided trades. nullable: true type: number winners: type: integer type: object type: array company: nullable: true type: object exposure: nullable: true type: object from: format: date type: string next_dividend: nullable: true type: object next_earnings: nullable: true type: object options: description: Open option positions per account. items: type: object type: array recent_trades: items: type: object type: array stocks: description: Open stock positions per account. items: type: object type: array summary: description: >- Closed-trade results of one group. Amounts are in USD and rates are fractions. properties: avg_loss: nullable: true type: number avg_win: nullable: true type: number expectancy: description: '`pnl / trades`, the average P&L per trade.' nullable: true type: number gross_loss: description: The sum of losing trades, zero or negative. type: number gross_profit: type: number key: description: The group, such as `calls`, `NVDA` or `0DTE`. type: string losers: type: integer pnl: description: Realized P&L in USD. type: number profit_factor: description: >- `gross_profit / abs(gross_loss)`. Null without losing trades. nullable: true type: number trades: type: integer win_rate: description: >- `winners / (winners + losers)`. Trades with zero P&L are left out. Null without decided trades. nullable: true type: number winners: type: integer type: object ticker: type: string tickers: description: The ticker and its option roots. items: type: string type: array to: format: date type: string trades_count: type: integer type: object title: Portfolio ticker 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 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: support@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 Payment_Required_Error: description: >- Returned with HTTP 402 when the API token was deactivated because a payment for the API subscription failed and the subscription is still unpaid. A successful payment restores access with the same token. Once the subscription is canceled, the token returns the 401 `unrecognized_token` error instead. Branch on `reason` rather than on `message`, whose wording can change. example: code: payment_required documentation_url: https://api.unusualwhales.com/docs message: >- This API token is paused because the payment for your API subscription failed. Update your card at https://unusualwhales.com/settings. The same token works again once a payment succeeds. reason: payment_failed request_id: GNI_YTC1CRnw2LACGBvE retryable: false support_email: support@unusualwhales.com token_url: https://unusualwhales.com/dashboard/api properties: code: description: Always `payment_required`. enum: - payment_required type: string documentation_url: description: Where to read this API documentation. type: string message: description: >- A plain description of the failure with the page where the card can be updated, written for a person. type: string reason: description: Always `payment_failed`. enum: - payment_failed 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 returns the same error until a payment for the subscription succeeds. 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: Payment Required 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: support@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_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 securitySchemes: authorization: scheme: bearer type: http ````