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

# Options Overview

> A live one-call options overview: implied vs realized volatility with rank, today's flow, the positioning book, expected moves, and probability bands.

Get a live one-call options overview for a ticker.
One full-chain snapshot is summarized into a volatility block (30-day implied vs 20-day
realized vol, their spread, skew, and the rank/percentile of today’s IV in the ticker’s
own year), a flow block (today’s volume with put/call splits and reference averages),
and a positioning block (open interest, max pain, and the largest open-interest
strikes). It adds expected moves per expiry (always including the first expiry on or
after the next earnings date), lognormal probability bands, quotable derived\[]
sentences, condition flags, and a data\_quality block.
History-dependent fields report null with a days-collected count while the daily series
fills, never fabricated.
Serves live data only; pass a past date to options\_sentiment instead.

**Endpoint:** `POST /api/v1/options/overview`

**Tier:** point · **Delivery:** sync

## Request

| Field        | Type     |
| ------------ | -------- |
| `ticker`     | `string` |
| `as_of_date` | `string` |

## Response

The response is the two-key envelope `{ finterm, data }`, where `data` is the `finterm.result:OptionsOverview/v1` contract:

| Field           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ticker`        | The stock ticker symbol, uppercased (e.g. "AAPL").                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `as_of_date`    | The calendar date the snapshot reflects, in YYYY-MM-DD format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `spot`          | The underlying spot price at the snapshot, or null when unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `context`       | Event context: next\_earnings carries the upcoming earnings date, the number of calendar days until it, and whether it is confirmed (null when no upcoming date is known).                                                                                                                                                                                                                                                                                                                                                                                         |
| `volatility`    | Volatility block, all in percent points: iv\_30 (30-day constant-maturity at-the-money implied vol), hv\_20 (20-day realized vol), iv\_vs\_hv (their spread), skew (near-the-money put-minus-call IV), iv\_rank and iv\_percentile (position of today's IV30 in its own trailing-year range and the share of days below it, 0-100), iv\_1y\_low / iv\_1y\_high (the year's IV extremes with their dates), and hv\_rank (the interim realized-vol rank). Rank, percentile, and the 1-year extremes are null until the daily series has collected a year of history. |
| `flow`          | Today's options volume: total volume with the put and call splits, pc\_ratio (put ÷ call volume), vs\_avg\_30d (today vs the trailing 30-day average, 1.15 = 115%), pc\_5d\_avg (trailing 5-day average volume P/C), and pc\_percentile\_1y (today's volume P/C percentile in the trailing year, 0-100). The averages and percentile are null while the daily series accumulates.                                                                                                                                                                                  |
| `positioning`   | The accumulated open-interest book: open\_interest with the put and call splits, pc\_ratio, vs\_avg\_30d (today's OI vs its trailing 30-day average), max\_pain (the strike with the least total option value at expiry, the expiry it applies to, and spot\_vs = spot ÷ strike − 1), and top\_strikes (the largest open-interest strikes per side as \[strike, share-of-side-OI] pairs).                                                                                                                                                                          |
| `expected_move` | Per-expiry expected moves from the at-the-money straddle: expiry, days ahead, pct (the ±% move) and dollars (the ± dollar move). The entry on or after the next earnings date carries post\_earnings: true so the event-spanning move is never missed.                                                                                                                                                                                                                                                                                                             |
| `probability`   | Lognormal price bands at one target expiry (the first post-earnings expiry when one is known): expiry, method, and bands with the p10/p25/p50/p75/p90 price levels. Null when no bands could be computed.                                                                                                                                                                                                                                                                                                                                                          |
| `derived`       | Quotable plain-English sentences summarizing flow, volatility, and the priced-in move. The first sentence doubles as a headline.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `flags`         | Notable conditions on this snapshot (e.g. volume\_above\_average, iv\_rank\_high, pc\_volume\_high\_extreme, chain\_truncated).                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `scope`         | What was summarized: selection (full\_chain or partial\_chain when the fetch cap stopped at a prefix), contracts\_analyzed, expirations\_covered, and pages\_fetched.                                                                                                                                                                                                                                                                                                                                                                                              |
| `data_quality`  | Reading reliability: status ("ok", "thin" for a sparse or zero-volume chain, or "no\_data"), history (status and days\_collected for the trailing daily series the rank/average fields depend on), and an optional note describing any caveat.                                                                                                                                                                                                                                                                                                                     |
| `methodology`   | A versioned description of how each figure is computed (iv\_30, hv\_20, skew, expected\_move, probability\_bands, max\_pain, and the flag\_thresholds), so explanations stay grounded in the actual computation.                                                                                                                                                                                                                                                                                                                                                   |

## Example

```bash theme={"system"}
finterm tool options_overview TSLA
```