- Live API Reference
- Flow Analytics
- Flow Signals
- Flow Signals
Flow Signals API
Scored, classified unusual-flow feed for one underlying. Sweep vs block, NBBO aggressor, opening/closing bias, directional intent, and a transparent 0-100 score with component breakdown and chain enrichment.
Endpoint
X-Api-Key)
Rate Limited: Yes
Plan: Alpha+
Parameters
| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
symbol |
path | string | required | - | Underlying symbol |
minScore |
query | number | 0 |
Drop signals below this score (0-100). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range. | |
intent |
query | enum | all | Filter by bullish / bearish / neutral. Unrecognized values are ignored. |
|
structure |
query | enum | all | Filter by block / sweep. A lone block-sized print is a block; sweep = ≥2 same-side prints on one contract within ~500ms. Unrecognized values are ignored. |
|
windowMinutes |
query | integer | 240 |
Look-back window in minutes (1-10080). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range. | |
limit |
query | integer | 50 |
Max signals returned (1-500). Non-numeric values return a 400 problem-details body. Out-of-range values are clamped to the supported range. | |
expiry |
query | date | all expiries | Filter the chain to a single expiry (yyyy-MM-dd). Invalid values return 400 invalid_expiry. An expiry with no data returns an empty result, not an error. |
Request
curl -H "X-Api-Key: YOUR_API_KEY" \
"https://lab.flashalpha.com/v1/flow/signals/NVDA?minScore=70&structure=sweep&windowMinutes=240"import requests
resp = requests.get(
"https://lab.flashalpha.com/v1/flow/signals/NVDA",
params={"minScore": 70, "structure": "sweep", "windowMinutes": 240},
headers={"X-Api-Key": "YOUR_API_KEY"}
)
resp.raise_for_status()
data = resp.json()
for sig in data["signals"]:
print(f"{sig['ts']} {sig['structure']:>5} {sig['right']} {sig['strike']} "
f"score={sig['score']} intent={sig['intent']} premium=${sig['premium']:,.0f}")const params = new URLSearchParams({
minScore: 70, structure: "sweep", windowMinutes: 240
});
const resp = await fetch(
`https://lab.flashalpha.com/v1/flow/signals/NVDA?${params}`,
{ headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
data.signals.forEach(s =>
console.log(`${s.ts} ${s.structure} ${s.right}${s.strike} score=${s.score} ${s.intent}`)
);Try it live
Runs on live market data and uses 1 request from your daily quota.
Response
{
"symbol": "NVDA",
"as_of": "2026-10-30T13:46:02.5129214Z",
"window_minutes": 240,
"expiry": null,
"underlying_price": 206.435,
"chain": {
"call_wall": 220,
"put_wall": 200,
"max_pain": 200,
"gamma_flip": 208.1809,
"gamma_flip_status": "available"
},
"count": 1,
"signals": [
{
"ts": "2026-10-30T13:38:49.745Z",
"expiry": "2026-10-30",
"strike": 210,
"right": "C",
"side": "buy",
"price": 0.32,
"size": 1411,
"premium": 45152,
"dte": 0,
"structure": "sweep",
"aggressor": "at_ask",
"open_close_bias": "opening_bias",
"open_close_confidence": 0.43,
"contract_net_oi_delta": 375,
"intent": "bullish",
"score": 70,
"conviction": "medium",
"tags": [
"sweep",
"opening",
"0dte"
],
"score_breakdown": {
"premium": 12,
"size_vs_oi": 6,
"aggressor": 14,
"sweep": 18,
"opening_bias": 9,
"tenor": 11
},
"enrichment": {
"iv": 0.55077,
"delta": 0.123889,
"gamma": 0.067453,
"iv_vs_atm": -0.00157,
"moneyness": "OTM",
"estimated_delta_notional": 3608629,
"hypothetical_gex_impact_if_opening": 4055957
}
}
],
"endpoint_version": "2026.09.30",
"data_as_of": {
"node": "fa5",
"equity_feed": "2026-10-30T13:46:02.141Z",
"equity_options_feed": "2026-10-30T13:46:01Z",
"index_feed": "2026-10-30T13:46:02.132Z",
"index_options_feed": "2026-10-30T13:45:59Z",
"futures_feed": "2026-10-30T13:45:51.589Z",
"futures_options_feed": "2026-10-30T13:45:51.596Z",
"flow_feed": "2026-10-30T13:45:00Z",
"oi_feed": "2026-10-29T20:00:00Z",
"macro_feed": "2026-10-29T21:00:20Z"
}
}Sending request…
See this endpoint on live data
Send this exact request and the real response shows up here, right next to the example.
Per-signal fields
| Field | Type | Description |
|---|---|---|
ts | string | ISO 8601 timestamp of the print (or last leg of a sweep) |
expiry / strike / right | string / number / string | Contract key (right is C or P) |
side | string | Upstream aggressor classification: buy, sell, or mid |
price / size / premium | number | premium = price × size × 100 |
dte | number | Days to expiry |
structure | string | block (lone block-sized print) or sweep (≥2 same-side prints on one contract within ~500ms) |
aggressor | string | NBBO aggressor strength at trade: above_ask / at_ask / mid / at_bid / below_bid |
open_close_bias | string | Contract-level OI-simulator bias: opening_bias, closing_bias, or unknown |
open_close_confidence | number | OI simulator's confidence weight |
contract_net_oi_delta | number | Simulator's signed net intraday OI delta for the contract |
intent | string | Directional intent: bullish, bearish, or neutral |
score | number | Composite score 0-100, ordered highest first |
conviction | string | Score bucket label (e.g. high) |
tags | array of string | Any of sweep, block, opening, closing, 0dte, whale (premium ≥ $1M), golden (top decile in response and score ≥ 70) |
score_breakdown | object | Sub-components that sum to score: premium, size_vs_oi, aggressor, sweep, opening_bias, tenor |
score_breakdown.premium | number | score component: premium |
score_breakdown.size_vs_oi | number | score component: size vs open interest |
score_breakdown.aggressor | number | score component: aggressor strength |
score_breakdown.sweep | number | score component: sweep structure |
score_breakdown.opening_bias | number | score component: opening bias |
score_breakdown.tenor | number | score component: tenor |
enrichment | object | Context from the settled chain snapshot at the signal's strike |
enrichment.iv / delta / gamma | number, nullable | Greeks from the settled chain snapshot at the signal's strike |
enrichment.iv_vs_atm | number, nullable | Signal IV minus ATM IV for the expiry |
enrichment.moneyness | string | ITM / ATM / OTM / unknown |
enrichment.estimated_delta_notional | number, nullable | Delta-weighted dollar notional for the print (delta-equivalent shares × spot) |
enrichment.hypothetical_gex_impact_if_opening | number, nullable | Standalone gamma-$ this print would add if opening and fully dealer-absorbed. Not applied to the live chain |
Top-level fields
| Field | Type | Description |
|---|---|---|
symbol | string | Underlying symbol |
as_of | string | Timestamp of the data (ISO 8601, UTC) |
window_minutes | number | Echo of the requested look-back window |
expiry | string | Echo of the requested expiry filter (or null if all expiries) |
underlying_price | number | Spot at request time (0 when the settled chain snapshot is unavailable) |
chain | object | Settled-chain reference levels |
chain.call_wall / put_wall / max_pain / gamma_flip | number | Settled-chain reference levels, computed once per request |
chain.gamma_flip_status | string | available when gamma_flip is a certified level; any other value means the level is unverified or missing. See GEX. |
count | number | Number of signals returned (after filters and limit) |
signals | array | Array of signals, highest score first |
endpoint_version, data_as_of | string, object | Response envelope, see Response envelope. |
Errors
| Status | Error | When |
|---|---|---|
400 | invalid_expiry | expiry is not a valid yyyy-MM-dd date. |
400 | - | A query value has the wrong type, or a required value is missing. The body is an RFC 7807 problem-details object with errors.<param>. |
401 | - | Missing or invalid X-Api-Key. The body is empty; check the status code before parsing JSON. |
403 | tier_restricted | Your plan is below Alpha. The body includes current_plan and required_plan. |
429 | Quota exceeded | Daily quota used up. Retry-After gives the seconds until the reset at 00:00 UTC. Rejected requests (including 403) count toward the quota. |
How Scoring Works
Every block-sized print in the window is coalesced into a signal, classified, and scored on a 0-100 scale. score_breakdown returns the component contributions that sum to score. The components map to the trade characteristics they're named after:
premium- contribution from the print's dollar premiumsize_vs_oi- contribution from print size relative to the contract's existing open interestaggressor- contribution from NBBO aggressor strength; the score weights conviction in the trade's own directionsweep- contribution when the print is part of a same-side sweep across ≥2 quotes within ~500msopening_bias- contribution when the OI simulator's contract-level bias says the position is being opened rather than unwoundtenor- contribution from the contract's DTE
Weights are server-tunable, so absolute component contributions may shift over time, but the components keep summing to score and overall signal ordering stays stable across tuning changes. The golden tag fires only when the score is in the response's top decile and at least 70 absolute, so a weak window may yield none at all.
Notes & Caveats
open_close_biasis a contract-level signal from the OI simulator's net intraday delta. It is not a per-print opening/closing label - individual trades inside the same contract carry the same bias.intentcollapses toneutralwheneveropen_close_biasisclosing_bias(direction can't be attributed on unwinds) or when the tradesideismid. Thesidefield (buy/sell/mid) is distinct from the NBBOaggressorlabel.structureis alwaysblockorsweep.singleis reserved and not currently emitted, so filteringstructure=singlereturns nothing.enrichment.*fields arenullandmoneynessis"unknown"when the signal's contract isn't in the settled chain snapshot (illiquid / just-listed).hypothetical_gex_impact_if_openingis explicitly conditional - the standalone gamma-$ this single print would add if opening and fully dealer-absorbed. It is not applied to the live chain (which already folds in intraday OI), so don't sum it against/v1/flow/gex.- If the settled chain snapshot is unavailable for the symbol, the feed degrades rather than 404s: scoring still runs on trade + OI-simulator context, but
underlying_priceis0, allchainlevels arenull, and everyenrichmentblock is null/"unknown".
Common Use Cases
- Run an unusual-activity feed - filter by
minScoreandstructure=sweepto drop a "smart-money tape" into a watchlist and surface only high-conviction prints - Alert on directional intent - fire when
intent=bullishorintent=bearisharrives withconviction=highand theopeningtag, so you act only on fresh positioning - Separate sweeps from blocks - branch on
structure(sweepvsblock) to treat aggressive cross-venue sweeps and negotiated blocks as different signals - Trigger flow-confirmed entries - require a same-side high-
scoresweep before sizing into a directional trade so flow agrees with your thesis - Hunt catalysts - scan for the
whaletag (≥$1M premium) to catch name-specific positioning ahead of the move - Research the score - use
score_breakdownto back-test which components drove the best forward returns across your universe and tune your filters
Related
Related reading
- Flow Signals API: scoring unusual options activity - how the score and its components are built
- Build an unusual-options-activity scanner (Python) - a worked scanner over this feed
- Options sweep detection: the 500ms coalescing rule - how sweeps are coalesced and classified
Complementary endpoints
- Flow Summary - the dealer-positioning headline to pair with individual signals
- Flow Signals Summary - aggregated counts and net intent across the signal feed
- Flow Live - full live bundle for the levels and GEX context behind a signal
Unlock DEX, VEX and CHEX with Basic
Everything in Free, plus:
- DEX, VEX and CHEX exposure
- Full max pain
- ETF & index symbols SPY, QQQ, SPX, VIX
Go full-chain with Growth
Everything in Basic, plus:
- Full-chain GEX Every expiration
- 0DTE analytics
- Exposure summary & AI narrative
- CME futures & live screener
Add history and vol surfaces with Alpha
Everything in Growth, plus:
- Historical API replay Since 2017
- SVI vol surfaces
- VRP analytics
- Greeks surfaces Vanna, charm, volga and speed grids