---
title: "IV rank snapshot"
method: GET
path: "/options-flow/iv-rank"
tags: ["Derived Analytics"]
---

# IV rank snapshot

`GET /options-flow/iv-rank`

## Request

- Base URL: `https://optionsbell.com/api/v1`
- URL: `https://optionsbell.com/api/v1/options-flow/iv-rank`
- Auth: API key in header `X-API-Key`

IV rank and IV percentile per symbol as of the latest available day,
computed from each symbol's history of daily average IV (percent).

- `*_iv_rank` = `(current - min) / (max - min)` over the window, 0..1;
  null when max equals min.
- `*_iv_percentile` = share of sessions with lower IV, 0..1.
- `side` picks the rank used for `min_rank` / `max_rank`, for
  ordering and for the `iv_rank` field: `call`, `put`, or `both`
  (default) = `GREATEST(call_iv_rank, put_iv_rank)`.
- Default lookback is the full available history; `lookback_days`
  restricts it. Symbols with fewer than 20 sessions are excluded.

Ordered by `iv_rank` descending, then symbol.

## Query parameters

- `symbols` string
- `side` 'call' | 'put' | 'both'
- `min_rank` number
- `max_rank` number
- `lookback_days` integer
- `limit` integer

## Response `200`

IV rank rows

- object
  - `date` string, date, nullable, required
  - `side` 'call' | 'put' | 'both', required
  - `lookback_days` integer, nullable, required: Echo of the parameter; null = full history.
  - `count` integer, required
  - `data` IvRankRow[], required
    - `symbol` string
    - `date` string, date
    - `sector` string, nullable
    - `industry` string, nullable
    - `iv_rank` string, nullable: Numeric string. The rank selected by `side`.
    - `current_call_iv` string: Numeric string. Percent.
    - `current_put_iv` string: Numeric string. Percent.
    - `call_iv_rank` string, nullable: Numeric string, 0..1.
    - `put_iv_rank` string, nullable: Numeric string, 0..1.
    - `call_iv_percentile` number
    - `put_iv_percentile` number
    - `min_call_iv` string: Numeric string.
    - `max_call_iv` string: Numeric string.
    - `min_put_iv` string: Numeric string.
    - `max_put_iv` string: Numeric string.
    - `lookback_days` string: Numeric string. Sessions in the window (>= 20).
    - `history_start` string, date

## Other responses

- `400`: Invalid input: `INVALID_PARAM`, `INVALID_SYMBOLS`.
- `401`: Missing or invalid API key: `MISSING_API_KEY`, `INVALID_API_KEY_FORMAT`, `INVALID_API_KEY`. No rate-limit headers.
- `403`: Key is valid but has no usable subscription: `NO_ACTIVE_SUBSCRIPTION` (no Personal plan on the key) or `SUBSCRIPTION_INACTIVE` (past due, paused, expired, or canceled past its period end). No rate-limit headers.
- `429`: Rate limit exceeded: `RATE_LIMIT_MINUTE` (60/min) or `RATE_LIMIT_DAY` (4,000/day). Carries both rate-limit header sets and `Retry-After` (seconds until the exhausted window opens again). Rejected requests count against the minute window, so back off instead of retrying immediately.
- `500`: Unexpected server error: `INTERNAL_ERROR`. The body and the X-Request-Id header carry the request id.
- `503`: Authentication backend unreachable: `AUTH_UNAVAILABLE`. Retry later. No rate-limit headers.

---

[API](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api.md) · [All operations](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api/llms.txt) · [OpenAPI document](https://skmtc.dev/optionsbell/apis/optionsbell-options-flow-api/revisions/42db9bcaa61f?raw)