- API Reference
- Earnings
- Earnings VRP
Lab API
Earnings VRP
Earnings VRP API
Earnings volatility-risk-premium: the live event-implied move vs. the symbol's realized history of actual moves, with a richness assessment and surprise-reaction breakdown.
Endpoint
Auth required (
X-Api-Key)
Rate Limited: Yes
Alpha 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/vrp/AAPL"import requests
resp = requests.get(
"https://lab.flashalpha.com/v1/earnings/vrp/AAPL",
headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"Premium ratio: {data['earnings_vrp']['premium_ratio']}")const resp = await fetch(
"https://lab.flashalpha.com/v1/earnings/vrp/AAPL",
{ headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("Premium ratio: " + data.earnings_vrp.premium_ratio);Response
{
"symbol": "AAPL",
"underlying_price": 212.34,
"as_of": "2026-06-05T15:42:10Z",
"earnings_date": "2026-06-09",
"days_to_event": 4,
"earnings_vrp": {
"implied_move_pct": 4.6,
"realized_median": 3.1,
"realized_mean": 3.4,
"premium_ratio": 1.48,
"z_score": 0.92,
"percentile": 70,
"assessment": "slightly_rich",
"directional_bias": "downside_overpriced"
},
"surprise_reaction": {
"beat_avg_move_pct": 2.8,
"miss_avg_move_pct": -5.1,
"inline_avg_move_pct": 0.4
}
}Key Response Fields
| Field | Description |
|---|---|
earnings_vrp.implied_move_pct | Live earnings-implied move (%); falls back to the stored implied move if the term structure can't be decomposed. |
earnings_vrp.realized_median / realized_mean | Median / mean of historical absolute actual moves (%). |
earnings_vrp.premium_ratio | implied_move / realized_median - >1 means options are pricing more than history realized. |
earnings_vrp.z_score | Implied move vs. realized distribution (z); null when fewer than 5 historical moves. |
earnings_vrp.percentile | Percentile of the implied move within historical realized moves; null when fewer than 5 events. |
earnings_vrp.assessment | Richness classification: rich, slightly_rich, fair, slightly_cheap, cheap, or insufficient_data. |
earnings_vrp.directional_bias | downside_overpriced / upside_overpriced when one side's historical moves dominate; otherwise null. |
surprise_reaction.beat_avg_move_pct | Avg actual move (%) following EPS beats (surprise > 1%); nullable. |
surprise_reaction.miss_avg_move_pct | Avg actual move (%) following EPS misses (surprise < −1%); nullable. |
surprise_reaction.inline_avg_move_pct | Avg actual move (%) following in-line results (−1%…+1% surprise); nullable. |
Errors
| Status | Description |
|---|---|
403 | Caller is below the Alpha tier. |
404 | no_data - no upcoming earnings for the symbol; or symbol_not_found - no live market data. |
About
Earnings VRP compares the option market's live event-implied move against the symbol's own realized history of post-earnings moves. The headline premium_ratio divides the implied move by the realized median, so values above 1 mean the options are pricing a bigger move than the stock has historically delivered.
The assessment field collapses that comparison into a plain richness label, while surprise_reaction breaks down the average post-event move conditional on EPS beats, misses, and in-line results to surface any directional skew.
Common Use Cases
- Decide whether to sell or buy event premium from
premium_ratioand the plain-languageassessmentlabel - Gauge how extreme the implied move is by reading
z_scoreandpercentileagainst realized history - Skew a structure to the cheaper wing when
directional_biasflags one side as overpriced - Stress-test a position with the beat / miss / in-line
surprise_reactionaverages to bound the post-print move - Require a minimum sample before acting by treating null
z_score/percentile(fewer than 5 events) orinsufficient_dataas a no-trade gate - Rank an earnings watchlist by
premium_ratioto surface the richest premium-selling candidates
Related
Related reading
- Single-stock VRP: earnings names vs SPY - why single-name event premium behaves differently from index VRP
- Complete guide to trading earnings volatility - the full workflow for trading rich vs. cheap event premium
Complementary endpoints
- Earnings overview - the hub tying together every earnings endpoint
- Earnings Expected Move - the implied-move input behind the premium ratio
- Earnings History - the realized moves the VRP is scored against
- Earnings Screener - rank the whole calendar by VRP richness in one call