Earnings History API

Endpoint

GET /v1/earnings/history/{symbol}

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

API Key

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`	ATM IV (%) immediately before and after the event.

Only events with an actual EPS result are returned (i.e., already-reported events).

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 already-reported events (those with an actual EPS result) are included, making this the historical base for VRP and IV-crush distribution analysis.

Common Use Cases

Backtest how often implied_move_pct over- or under-priced the realized actual_move_pct to set your own VRP edge
Build a per-symbol realized IV-crush distribution from iv_crush_pct to anchor premium-selling targets
Study the relationship between eps_surprise_pct and actual_move_pct to 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_iv and post_atm_iv when 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

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_pct series into a forward distribution
Earnings Expected Move - the live implied move you backtest against these actuals