- API Reference
- Earnings
- IV Crush
Earnings IV Crush API
Expected IV crush for the next event plus the symbol's historical IV-crush distribution: the live estimate is derived from the current pre/post-event term structure; the distribution is built from up to the last 20 events.
Endpoint
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 + "%");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: the latest 20 stored crush values. |
historical_context | Coverage counts, proxy medians and definitions link for the same 20-event sample (see Earnings History). |
methodology_url | Definitions of the stored proxies and the sample rule. |
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 uses the latest 20 stored crush values, as before. historical_context is computed separately from completed reports, so its counts can differ from count. Legacy stored crush can be a cross-expiry proxy rather than a measured decline.
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_pctagainst the historicalmedianto flag when the term structure is pricing crush rich or cheap - Size premium-selling structures against the
p25/p75crush range so the expected vega harvest covers realized downside - Set a minimum
pre_ivlevel and a targetpost_ivto qualify a short-vol candidate before the print - Stress-test a position against the
worsthistorical crush outcome and the small-sample risk implied bycount - Gate the trade when
current_estimateis null (no upcoming event or unresolved term structure) and fall back to thedistributionalone - Rank a watchlist by expected vs. realized crush gap to surface the richest premium-selling setups
Related
Related reading
- IV crush explained: the earnings volatility collapse - the mechanics behind the pre-to-post IV drop this endpoint measures
- Complete guide to trading earnings volatility - how to trade the crush as part of a full earnings playbook
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