---
title: "Option volatility summary by expiry"
method: GET
path: "/v1/derivatives/{underlying}/volatility"
tags: ["derivatives"]
---

# Option volatility summary by expiry

`GET /v1/derivatives/{underlying}/volatility`

## Request

- Base URL: `https://api.tapetide.com`
- URL: `https://api.tapetide.com/v1/derivatives/{underlying}/volatility`
- Auth: HTTP bearer

One row per session and listed option expiry: ATM implied volatility, IV rank and percentile, realised volatility (indices), risk reversal, butterfly, max pain and put-call ratios. History from 2001. Window defaults to the last 90 days (max 3 years); `expiry` restricts to one expiry. All volatility fields are percents. Realised-volatility fields are filled one session late, so the newest session can show them as null. Pages by date (newest first by default), then expiry.

## Path parameters

- `underlying` string, required: Underlying symbol as listed for derivatives, e.g. "NIFTY", "BANKNIFTY", "SENSEX", "RELIANCE". Percent-encode "&" (M%26M).

## Query parameters

- `expiry` string
- `from` string
- `to` string
- `order` 'asc' | 'desc'
- `limit` integer
- `cursor` string

## Response `200`

OK. Costs one request unit.

- object
  - `data` DerivativeVolatilityItem[], required
    - `date` string, required: Trading session (YYYY-MM-DD).
    - `expiry` string, required: Option expiry this row summarises (YYYY-MM-DD).
    - `days_to_expiry` number, nullable, required: Calendar days from `date` to `expiry`.
    - `forward` number, nullable, required: Forward price of the underlying for this expiry.
    - `forward_basis` 'futures' | 'put_call_parity' | 'spot_carry', nullable, required: How the forward was estimated (see option-analytics).
    - `atm_strike` number, nullable, required: Listed strike nearest the forward.
    - `atm_iv_pct` number, nullable, required: At-the-money implied volatility, annualised percent (average of call and put IV at `atm_strike`).
    - `iv_rank_pct` number, nullable, required: Where today's front-expiry ATM IV sits in its trailing 252-session high-low range, 0-100. Same value on every expiry row of a session.
    - `iv_percentile_pct` number, nullable, required: Share of the trailing 252 sessions with a lower front-expiry ATM IV, 0-100. Same value on every expiry row of a session.
    - `realised_vol_20d_pct` number, nullable, required: 20-session close-to-close realised volatility of the underlying, annualised percent. Index underlyings only; null for stocks.
    - `realised_vol_30d_pct` number, nullable, required: 30-session realised volatility, annualised percent. Index underlyings only.
    - `iv_minus_rv_30d_pct` number, nullable, required: `atm_iv_pct` minus `realised_vol_30d_pct`, percentage points. Index underlyings only.
    - `risk_reversal_pct` number, nullable, required: OTM put IV minus OTM call IV, percentage points, using the listed strikes nearest 93% and 107% of the forward (a fixed-moneyness wing, not a delta-matched one). Positive = puts richer.
    - `butterfly_pct` number, nullable, required: Average of those two wing IVs minus ATM IV, percentage points (smile curvature).
    - `max_pain_strike` number, nullable, required: Strike at which the total intrinsic value owed to option holders at expiry is smallest, from session-end open interest.
    - `call_open_interest_units` number, nullable, required: Total call open interest across strikes, in units of the underlying.
    - `put_open_interest_units` number, nullable, required: Total put open interest across strikes, in units of the underlying.
    - `put_call_ratio_oi` number, nullable, required: Put open interest / call open interest. Null when call OI is 0.
    - `put_call_ratio_volume` number, nullable, required: Put volume / call volume. Null when call volume is 0.
    - `strikes` number, nullable, required: Number of strikes that contributed to this summary.
  - `meta` ListMeta, required
    - `as_of` string, date-time, required: When this response was assembled (UTC).
    - `route` string, required: operationId that served the request.
    - `count` integer, required: Items in this page.
    - `limit` integer, required: Page size applied.
    - `has_more` boolean, required: Whether another page exists.
    - `next_cursor` string, nullable, required: Pass as `cursor` to fetch the next page; null on the last page.
  - `links` Links, required
    - `next` string, nullable: Relative URL of the next page, or null.

## Other responses

- `400`: Malformed or out-of-range parameter. Not charged.
- `401`: Missing or invalid bearer token.
- `404`: The requested resource does not exist. Not charged.
- `429`: Per-minute burst cap (`rate_limited`) or plan quota (`quota_exhausted`) reached.
- `500`: Unexpected server error. Not charged.
- `502`: A data dependency was unavailable. Not charged.
- `503`: Authentication or quota service temporarily unavailable (`service_unavailable`). Not charged; retry after `Retry-After` seconds.

---

[API](https://skmtc.dev/tapetide/apis/tapetide-api.md) · [All operations](https://skmtc.dev/tapetide/apis/tapetide-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tapetide/apis/tapetide-api/revisions/261ec086bde5?raw)