Earnings Screener API

Endpoint

GET /v1/earnings/screener

Auth required (X-Api-Key) Rate Limited: Yes Alpha plan+

Parameters

Name	In	Required	Default	Description
`sort`	query	no	`vrp_richest`	Ranking: `vrp_richest` (highest premium ratio), `cheapest_move` (lowest implied move), `highest_crush` (highest median IV crush), or `importance`. Unrecognized values fall back to `vrp_richest`.
`limit`	query	no	`20`	Max rows returned. Clamped to `1`–`50`.
`days`	query	no	`14`	Forward window in days. Clamped to `1`–`60`.
`min_importance`	query	no	-	Only include events with `importance >=` this value.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/earnings/screener?sort=vrp_richest&limit=20&days=14&min_importance=3"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/earnings/screener",
    params={"sort": "vrp_richest", "limit": 20, "days": 14, "min_importance": 3},
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"Matched events: {data['count']}")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/earnings/screener?sort=vrp_richest&limit=20&days=14&min_importance=3",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("Matched events: " + data.count);

API Key

Response

{
  "events": [
    {
      "symbol": "AAPL",
      "company_name": "Apple Inc",
      "earnings_date": "2026-06-09",
      "days_to_event": 4,
      "timing": "amc",
      "importance": 5,
      "implied_move_pct": 4.6,
      "premium_ratio": 1.48,
      "iv_crush_median": 38.5,
      "assessment": "slightly_rich"
    }
  ],
  "count": 1
}

Key Response Fields

Field	Description
`events[].premium_ratio`	VRP premium ratio (implied / realized-median); null when no historical actual moves exist.
`events[].iv_crush_median`	Median historical IV crush (%); null when no crush history.
`events[].assessment`	VRP richness classification (`rich`, `slightly_rich`, `fair`, `slightly_cheap`, `cheap`, `insufficient_data`); null when no history.
`count`	Total matched events before `limit` is applied (the `events` array is capped at `limit`).

Errors

Status	Description
`400`	Invalid query parameter.
`403`	Caller is below the Alpha tier.
`404`	`no_data` - no upcoming earnings in the requested window.

About

The Earnings Screener ranks every upcoming earnings event in a forward window so you can surface the most actionable names in one call. Choose a ranking via sort - richest VRP premium, cheapest implied move, highest historical IV crush, or event importance.

Narrow the universe with days to set the lookahead window and min_importance to drop minor names. The count field reports the full match total before limit trims the returned events array.

Common Use Cases

Build a weekly earnings watchlist of the richest VRP names with sort=vrp_richest ranked on premium_ratio
Hunt cheap long-volatility events via sort=cheapest_move to find underpriced implied_move_pct
Target premium-selling candidates with sort=highest_crush using iv_crush_median
Filter to major reports only with min_importance and tune the lookahead with days
Page the full calendar by reading count (matches before limit) against the returned events length
Drop names lacking history by skipping rows where premium_ratio / assessment are null or insufficient_data

Complementary endpoints

Earnings overview - the hub tying together every earnings endpoint
Earnings VRP - the full VRP breakdown for a single name you surfaced
Earnings Strategies - ranks structures once the screener picks the symbol
Earnings IV Crush - the crush detail behind the highest_crush sort