Earnings IV Crush API

Endpoint

GET /v1/earnings/iv-crush/{symbol}

Auth required (X-Api-Key) Rate Limited: Yes Growth plan+

Parameters

Name	In	Required	Default	Description
`symbol`	path	yes	-	Underlying symbol (case-insensitive).

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/earnings/iv-crush/AAPL"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/earnings/iv-crush/AAPL",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"Expected crush: {data['current_estimate']['expected_crush_pct']}%")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/earnings/iv-crush/AAPL",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("Expected crush: " + data.current_estimate.expected_crush_pct + "%");

API Key

Response

{
  "symbol": "AAPL",
  "as_of": "2026-06-05T15:42:10Z",
  "earnings_date": "2026-06-09",
  "current_estimate": {
    "expected_crush_pct": 41.23,
    "pre_iv": 67.8,
    "post_iv": 39.85
  },
  "distribution": {
    "median": 38.5,
    "p25": 31.0,
    "p75": 45.2,
    "worst": 12.4,
    "best": 58.9,
    "count": 12
  }
}

Key Response Fields

Field	Description
`earnings_date`	Next event date; null when no upcoming event but history exists.
`current_estimate`	Live crush estimate; null when no upcoming event or the term structure can't be resolved.
`current_estimate.expected_crush_pct`	Expected ATM IV drop (%) from pre to post event = `(pre_iv - post_iv) / pre_iv x 100`.
`current_estimate.pre_iv` / `post_iv`	ATM IV (%) of the latest pre-event and earliest post-event expiry.
`distribution.median` / `p25` / `p75`	Historical realized crush (%) percentiles.
`distribution.worst` / `best`	Smallest and largest historical crush (%).
`distribution.count`	Number of historical events in the distribution.

Errors

Status	Description
`403`	Caller is below the Growth tier.
`404`	`no_data` - no upcoming event and no IV-crush history for the symbol.

About

Pairs a live, forward-looking IV-crush estimate for the next event with the symbol's realized crush distribution. The current estimate is derived from the latest pre-event and earliest post-event ATM IV in the term structure; the distribution summarizes up to the last 20 reported events.

The current_estimate is null when there is no upcoming event or the term structure can't be resolved, while the distribution still reflects history when available.

Common Use Cases

Compare the live expected_crush_pct against the historical median to flag when the term structure is pricing crush rich or cheap
Size premium-selling structures against the p25/p75 crush range so the expected vega harvest covers realized downside
Set a minimum pre_iv level and a target post_iv to qualify a short-vol candidate before the print
Stress-test a position against the worst historical crush outcome and the small-sample risk implied by count
Gate the trade when current_estimate is null (no upcoming event or unresolved term structure) and fall back to the distribution alone
Rank a watchlist by expected vs. realized crush gap to surface the richest premium-selling setups

Complementary endpoints

Earnings overview - the hub tying together every earnings endpoint
Earnings Expected Move - the term kink driving the crush you are estimating here
Earnings History - the realized-event base behind this crush distribution
Earnings Strategies - ranks premium-selling structures that monetize the crush