- API Reference
- Earnings
- Earnings History
Lab API
Earnings History
Earnings History API
Past earnings events for the symbol with EPS/revenue actuals and surprises, implied vs. actual moves, and realized IV crush.
Endpoint
Auth required (
X-Api-Key)
Rate Limited: Yes
Growth plan+
Parameters
| Name | In | Required | Default | Description |
|---|---|---|---|---|
symbol |
path | yes | - | Underlying symbol (case-insensitive). |
limit |
query | no | 12 |
Number of most-recent reported events to return. Clamped to 1-40. |
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://lab.flashalpha.com/v1/earnings/history/AAPL?limit=12"import requests
resp = requests.get(
"https://lab.flashalpha.com/v1/earnings/history/AAPL",
headers={"X-Api-Key": "YOUR_API_KEY"},
params={"limit": 12}
)
data = resp.json()
print(f"{data['count']} reported events")const resp = await fetch(
"https://lab.flashalpha.com/v1/earnings/history/AAPL?limit=12",
{ headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log(data.count + " reported events");Response
{
"symbol": "AAPL",
"count": 2,
"history": [
{
"date": "2026-04-30",
"fiscal_period": "Q2",
"fiscal_year": 2026,
"eps_estimate": 1.50,
"eps_actual": 1.58,
"eps_surprise_pct": 5.33,
"revenue_actual": 95800000000,
"revenue_surprise_pct": 1.2,
"implied_move_pct": 4.9,
"actual_move_pct": -3.1,
"iv_crush_pct": 38.5,
"pre_atm_iv": 64.2,
"post_atm_iv": 39.5
}
]
}Key Response Fields
| Field | Description |
|---|---|
history[].eps_surprise_pct | EPS surprise vs. estimate (%); positive = beat. |
history[].revenue_surprise_pct | Revenue surprise vs. estimate (%); nullable. |
history[].implied_move_pct | Earnings-implied move (%) priced before the event. |
history[].actual_move_pct | Realized post-earnings move (%); sign indicates direction. |
history[].iv_crush_pct | Realized IV crush (%) from pre- to post-event ATM IV. |
history[].pre_atm_iv / post_atm_iv | Stored ATM IVs (%). Legacy backfill took both from one pre-event snapshot (earnings-loaded vs clean expiry), so iv_crush_pct is a cross-expiry proxy, not a measured before/after decline. |
history[].timing | Report timing as stored (BMO, AMC, ...); nullable. |
history[].report_date_basis | calendar_report_date when the date has confirmed provenance, otherwise unknown. |
history[].iv_decline_proxy_vol_points | pre_atm_iv - post_atm_iv in vol points when both are finite. |
historical_context | Coverage of the returned sample: event, actual-move, implied-move, paired and IV-pair counts with missing counts, proxy medians, first/last event dates, coverage_status and methodology_url. Descriptive only. |
history rows are the latest stored events with an EPS actual, as before. historical_context is computed separately from completed reports only: events dated before today (ET), one per fiscal quarter, where a finite EPS actual or realized move establishes the report.
Errors
| Status | Description |
|---|---|
400 | Invalid limit. |
403 | Caller is below the Growth tier. |
404 | no_data - no reported earnings history for the symbol. |
About
Returns up to the most-recent 40 reported earnings events for a symbol, each carrying EPS/revenue actuals and surprises, the implied move priced before the event vs. the realized actual move, and the realized IV crush from pre- to post-event ATM IV.
Only reported quarters are included, making this the historical base for VRP and IV-crush distribution analysis. historical_context states how many events carry each stored measurement, so a median built from a few events is visible as such.
Common Use Cases
- Backtest how often
implied_move_pctover- or under-priced the realizedactual_move_pctto set your own VRP edge - Build a per-symbol realized IV-crush distribution from
iv_crush_pctto anchor premium-selling targets - Study the relationship between
eps_surprise_pctandactual_move_pctto model beat/miss reaction asymmetry - Track beat/miss consistency across fiscal periods to gauge how predictable a name's prints are
- Recompute the realized crush from
pre_atm_ivandpost_atm_ivwhen you need the raw IV levels, not just the percentage - Seed live VRP and IV-crush models with this already-reported history as their realized base
Related
Related reading
- Complete guide to trading earnings volatility - how realized event history feeds the rest of the earnings playbook
Complementary endpoints
- Earnings overview - the hub tying together every earnings endpoint
- Earnings VRP - scores live implied move against this realized history
- Earnings IV Crush - turns this
iv_crush_pctseries into a forward distribution - Earnings Expected Move - the live implied move you backtest against these actuals