Earnings VRP API

Endpoint

GET /v1/earnings/vrp/{symbol}

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);

API Key

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_ratio and the plain-language assessment label
Gauge how extreme the implied move is by reading z_score and percentile against realized history
Skew a structure to the cheaper wing when directional_bias flags one side as overpriced
Stress-test a position with the beat / miss / in-line surprise_reaction averages to bound the post-print move
Require a minimum sample before acting by treating null z_score/percentile (fewer than 5 events) or insufficient_data as a no-trade gate
Rank an earnings watchlist by premium_ratio to surface the richest premium-selling candidates

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