Options Flow Leaderboard API

Endpoint

GET /v1/flow/options/leaderboard

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

Parameters

Name	In	Required	Default	Description
`n`	query	no	10	Rows per side; effective max is `50`
`windowMinutes`	query	no	240	Lookback window, clamped to `1..10080`

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/flow/options/leaderboard?n=10&windowMinutes=240"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/flow/options/leaderboard",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"Top buyer: {data['buyers'][0]['symbol']}")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/flow/options/leaderboard",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("Top buyer: " + data.buyers[0].symbol);

API Key

Response

{
  "generatedUtc": "2026-05-12T18:42:10Z",
  "n": 10,
  "windowMinutes": 240,
  "buyers": [
    {
      "symbol": "NVDA",
      "netVolume": 84520,
      "netNotional": 28450000,
      "buyVolume": 152400,
      "sellVolume": 67880,
      "avgPremium": 3.36,
      "tradeCount": 18420,
      "lastTradeUtc": "2026-05-12T18:42:08Z"
    },
    {
      "symbol": "SPY",
      "netVolume": 62300,
      "netNotional": 18420000,
      "buyVolume": 124500,
      "sellVolume": 62200,
      "avgPremium": 2.96,
      "tradeCount": 22150,
      "lastTradeUtc": "2026-05-12T18:42:09Z"
    }
  ],
  "sellers": [
    {
      "symbol": "TSLA",
      "netVolume": -54820,
      "netNotional": -16240000,
      "buyVolume": 38400,
      "sellVolume": 93220,
      "avgPremium": 2.96,
      "tradeCount": 14820,
      "lastTradeUtc": "2026-05-12T18:42:07Z"
    },
    {
      "symbol": "AAPL",
      "netVolume": -42150,
      "netNotional": -12480000,
      "buyVolume": 28400,
      "sellVolume": 70550,
      "avgPremium": 2.96,
      "tradeCount": 11240,
      "lastTradeUtc": "2026-05-12T18:42:06Z"
    }
  ]
}

Key Response Fields

Field	Type	Description
`generatedUtc`	string	Generation timestamp
`n`	integer	Effective rows per side
`windowMinutes`	integer	Effective lookback window
`buyers[]`	array	Positive net-notional rows: `symbol`, `netVolume`, `netNotional`, `buyVolume`, `sellVolume`, `avgPremium`, `tradeCount`, `lastTradeUtc`
`sellers[]`	array	Negative net-notional rows (same schema as `buyers[]`)

Errors

Status	Description
`403`	Requires Alpha plan or higher
`502`	Upstream flow data source unavailable

About

Ranks the option-flow universe by net notional over the requested window and returns the top buyers and sellers in a single payload. Responses are cached for 30 seconds on the server, so polling more often than that just returns the same snapshot.

Common Use Cases

Run a universe-wide flow scanner - pull buyers[] and sellers[] ranked by netNotional over a rolling windowMinutes to surface where money is moving right now
Seed a watchlist automatically - take the top n symbols by absolute netNotional to focus the day on the most-pressured names
Send a daily flow recap - format the buyers and sellers lists into an email or Slack post each session close
Separate conviction from churn - weigh netVolume against buyVolume/sellVolume and tradeCount to tell one-sided accumulation from two-way noise
Filter by premium tier - use avgPremium to split cheap lotto flow from expensive, higher-conviction positioning
Chart market-wide sentiment - snapshot aggregate buy versus sell netNotional across the leaderboard over time, refreshing no faster than the 30s cache

Complementary endpoints

Options Outliers - per-contract anomalies behind the top-ranked names
Options Summary - drill into a single ranked symbol's totals
Options Recent - the raw prints driving each leaderboard row
Flow Signals - scored unusual-activity layer built on this flow