> ## Documentation Index
> Fetch the complete documentation index at: https://api.unusualwhales.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> API requests use the base URL https://api.unusualwhales.com and require a bearer token in the `Authorization` header (`Authorization: Bearer <API_KEY>`). Create and manage API tokens at https://unusualwhales.com/dashboard/api.
> For live market data inside an AI tool, use the Unusual Whales MCP server at https://unusualwhales.com/public-api/mcp.
> Instructions for agents using Unusual Whales tools: https://unusualwhales.com/skill.md

# Conventions

How the API behaves across endpoints. Endpoint pages state anything specific to that endpoint.

## Response freshness

Responses are always computed fresh. There is no request caching and no `force_refresh` parameter. Two identical requests can return identical bytes simply because the underlying data has not changed on its update cadence. To check freshness, read a timestamp field in the payload (for example `tape_time`, or the newest `created_at`), rather than comparing raw response bodies. Every response carries a unique `x-request-id`.

## Reading response arrays

Array order is not uniform across endpoints, so each endpoint page states its order. Where an endpoint returns newest last (for example `iv-rank`), the current value is the last element. A few endpoints nest their rows under a key other than `data`: `shorts` volume-and-ratio uses `si`, and `option-contract/{id}/historic` uses `chains`.

## Empty is not an error

A `200` response with an empty `data` array means there is no data for the inputs you sent, not that the request failed. Common causes are a date with no trading, a symbol that does not apply to that dataset, or a missing required filter (for example `/api/stock/{ticker}/greeks` without `expiry`).

## Symbols and ticker types

Each endpoint states which symbol types it accepts (equities, ETFs, indices, crypto) and the expected format. Crypto pairs use the `BASE-QUOTE` form, for example `BTC-USD`. Index tickers (SPX, NDX, VIX, RUT) are supported on the greek and exposure endpoints, but not on raw quote or OHLC, where they return `422` (see the note on those endpoints).

## Point-in-time and availability

For time-series endpoints, three timestamps can differ: execution time, report time, and availability time. Some fields are forward-computed and will be `null` on recent rows (for example `realized_volatility`). Daily datasets are final only after the session closes, and open interest restates the next morning. History depth and update cadence vary by endpoint and are stated on each page. For a strict point-in-time build, gate on your own first-seen ingestion time rather than re-pulling past dates.

## Nullable fields

Fields that can be `null`, and why, are listed on each endpoint page. The common ones: greeks when the underlying is missing, `underlying_price` on the index tape, recent `realized_volatility` rows, `gamma_flip`, and `max-pain` close for NDX.

## Concept to route

Use these routes rather than guessing a name (guessed names return `404`).

| Concept | Route |
| - | - |
| Risk-reversal skew | `/api/stock/{ticker}/historical-risk-reversal-skew` |
| Variance risk premium | `/api/stock/{ticker}/volatility/variance-risk-premium` |
| Volatility summary | `/api/stock/{ticker}/volatility/stats` |
| Dealer gamma by strike | `/api/stock/{ticker}/greek-exposure/strike`, `/api/stock/{ticker}/spot-exposures/strike` |
| Cross-sectional volatility | `/api/volatility/anomaly/top`, `/api/volatility/character/top` |

There are no `volatility/skew`, `volatility/surface`, or `term-skew` routes.

## Request headers to watch

Every response includes usage headers: `x-uw-token-req-limit` is your daily cap, `x-uw-daily-req-count` is what you have used today (resets 8PM ET), and `x-request-id` is unique per call. Read these to manage your own rate rather than guessing.

## Data Shop and limits

Data older than your plan's lookback window is available as one-time downloads in the Data Shop. Your plan's lookback and daily request quota are listed in the pricing and limits reference.

## Example URLs

Each endpoint page shows one fully filled example URL and marks each parameter as path or query. Note that `technical-indicator/{function}` is a path segment, not `?function=`.

## Data retention and redistribution

You may keep and use API data for personal or internal purposes, including after you cancel. Redistributing the data to others requires a redistribution license. Contact [oskar@unusualwhales.com](mailto:oskar@unusualwhales.com).