Insights

Retrieve Historical IV Rank for Backtests

Alphanume Team · July 23, 2026

Retrieve historical IV Rank for backtests with fixed date filters and only_final=true, then keep rank, percentile, the trailing-year band, and settlement status together in the research panel.

Alphanume IV/HV Rank places each ticker's current implied and realized volatility inside its own strict trailing 252-observation history. The endpoint GET /v1/iv-rank returns the current values, 52-week ranks and percentiles, trailing highs, lows, medians, daily cross-sectional context, liquidity reference, and settlement fields.

For a historical upper-decile screen, query min_iv_rank=90 with only_final=true. That means the current IV sits in the top 10% of its own high-low band. It does not mean the ticker ranks in the top 10% of the day's universe, and it does not mean options are expected to fall in value.

Rank and percentile answer different questions

Measure	Definition	Sensitivity
iv_rank	Position between the trailing-year IV low and high, scaled 0 to 100	One extreme high or low changes the whole band
iv_percentile	Share of trailing observations below current IV, scaled 0 to 100	Uses the full empirical distribution
iv_rank_cs_ranked	Cross-sectional percentile of IV Rank on that date, scaled 0 to 1	Compares names with the day's universe
iv_rank_cs_z	Cross-sectional z-score of IV Rank	Sensitive to the day's cross-sectional shape

Rank follows (iv - iv_52w_low) / (iv_52w_high - iv_52w_low) * 100. Percentile asks how many of the 252 trailing observations were below today. They diverge after an isolated volatility spike because the old extreme can keep the range wide while most ordinary observations remain below the current value.

A ticker is absent until the source has a full 252-observation window. Recent listings and newly eligible names are missing rather than partially ranked, so the served universe changes through time.

Pull settled upper-band observations

Today's row refreshes through the session with is_final=0 and settles after the close around 4:30 PM New York time with is_final=1. Every past date is final. The default route returns the latest row per date and ticker, so a current-day research job must request final rows explicitly.

import os
import requests
import pandas as pd

response = requests.get(
    "https://api.alphanume.com/v1/iv-rank",
    headers={"X-API-Key": os.environ["ALPHANUME_API_KEY"]},
    params={
        "date_gte": "2024-01-01",
        "date_lte": "2025-12-31",
        "min_iv_rank": 90,
        "only_final": "true",
    },
    timeout=30,
)
response.raise_for_status()
rows = pd.DataFrame(response.json()["data"])

assert rows["is_final"].eq(1).all()
assert rows["iv_rank"].ge(90).all()
assert not rows.duplicated(["date", "ticker"]).any()

The route does not paginate, and results arrive by date descending then ticker ascending. Save the response count and raw JSON before joining forward outcomes. Free access covers a trailing 20-session delayed window, so a multi-year request requires historical access.

Keep the as-of screen separate from outcomes

Panel field	Available at screen time	Use
iv, iv_rank, iv_percentile	Yes on the settled observation	Define the name-relative IV state
hv, hv_rank, hv_percentile	Yes	Describe the realized-volatility context
n_obs_52w	Yes	Confirm the strict warm window
notional_volume	Yes	Liquidity reference, not an execution-cost estimate
forward option P&L	No	Attach later from a separately specified strategy

Freeze the screen before loading future volatility or option returns. Then define whether the test measures one-week IV change, one-month IV change, delta-hedged option P&L, or another outcome. These are different hypotheses, and a high rank does not choose among them.

Compare iv_rank with hv_rank and the absolute IV level. A quiet stock at rank 95 can still have lower implied volatility than a biotech at rank 20. Name-relative position is context, not a market-wide price comparison.

High rank is not a sell instruction

Catalyst risk. Earnings, trials, court decisions, and corporate events can justify a high IV reading.
Range distortion. One extreme observation can compress later ranks even when percentile stays high.
Outcome mismatch. Falling IV does not guarantee a profitable short-option trade after realized movement, skew, spreads, and hedging.
Universe changes. The 252-observation warm-up excludes recent names and can alter cross-sectional coverage.
Intraday leakage. A provisional row can change before settlement and should not enter a close-based historical screen.

The Alphanume proof page publishes the settled IV Rank mean-reversion study and its sample. That evidence concerns subsequent IV behavior across historical rows. It does not turn every high-rank row into a profitable options sale or remove the need for execution costs and event controls.

Reproduce one settled cohort

Pull one year with min_iv_rank=90 and only_final=true. Export raw rows, date-level counts, rank-versus-percentile summary, and tickers missing from the warm universe. Attach one predefined forward IV-change outcome only after the cohort is saved, and report scheduled catalysts separately.

Explore the screen on the IV Rank page and reproduce every field and filter from the IV Rank documentation.