---
title: "IV Rank & IV Percentile (52-week): answers \"is this name's volatility high or low"
method: GET
path: "/v1/iv-rank"
---

# IV Rank & IV Percentile (52-week): answers "is this name's volatility high or low

`GET /v1/iv-rank`

## Request

- Base URL: `https://api.alphanume.com`
- URL: `https://api.alphanume.com/v1/iv-rank`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

IV Rank & IV Percentile (52-week): answers "is this name's volatility high or low
*for itself*?" For each US optionable equity, per trading day: where current ~30-day
implied vol and 20-day realized vol sit inside that name's own trailing-year range --
iv_rank/hv_rank (0-100 position between the 52w low and high), iv_percentile /
hv_percentile (share of the past year's days below today), the 52w high/low/median
levels themselves, and daily cross-sectional ranks/z-scores for context. Rows update
intraday and settle after the close (is_final=1).

The classic premium-selling timing filter: min_iv_rank=50 finds names in the upper
half of their own vol range regardless of absolute vol level.

Requires an Alphanume Pro API key. A 403 PRO_SUBSCRIPTION_REQUIRED or
DATE_RANGE_RESTRICTED error means the key's plan does not cover the request --
it does not mean the data is missing.

## Query parameters

- `ticker` string
- `date` string
- `date_gte` string
- `date_lte` string
- `date_gt` string
- `date_lt` string
- `min_iv_rank` number
- `max_iv_rank` number
- `min_hv_rank` number
- `max_hv_rank` number
- `min_iv_percentile` number
- `only_final` boolean

## Response `200`

Matching rows.

- Envelope
  - `count` integer, required
  - `data` object[], required

## Other responses

- `400`: Invalid or conflicting query parameters.
- `401`: Missing or unrecognized API key.
- `403`: PRO_SUBSCRIPTION_REQUIRED: the key's plan does not include API access; every endpoint requires an active Pro subscription. DATE_RANGE_RESTRICTED: a legacy free-tier key asked for dates outside its window. In both cases the data is not missing.
- `429`: Rate limit exceeded (600/min); the body carries retry_after_seconds.

---

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