---
title: "Per-symbol IV rank series"
method: GET
path: "/options-flow/iv-rank/{symbol}"
tags: ["Derived Analytics"]
---

# Per-symbol IV rank series

`GET /options-flow/iv-rank/{symbol}`

## Request

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

One row per trading day, newest first, each carrying that day's call
and put average IV (percent) with its rank and percentile against the
symbol's full available history (or the last `lookback_days`).
`date` in the envelope is the newest day returned.

## Path parameters

- `symbol` string, required

## Query parameters

- `lookback_days` integer
- `limit` integer

## Response `200`

IV rank time series

- object
  - `symbol` string, required
  - `date` string, date, nullable, required
  - `lookback_days` integer, nullable, required
  - `count` integer, required
  - `data` IvRankSeriesRow[], required
    - `date` string, date
    - `call_iv` string: Numeric string. Percent.
    - `put_iv` string: Numeric string. Percent.
    - `call_iv_rank` string, nullable: Numeric string, 0..1; null when max == min.
    - `put_iv_rank` string, nullable: Numeric string, 0..1; null when max == min.
    - `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.
    - `history_start` string, date

## Other responses

- `400`: Invalid input: `INVALID_SYMBOL`, `INVALID_PARAM`.
- `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)