Flow

Premium by side, name and sector.

Premium flow for one symbol

GET/v1/symbols/{symbol}/flow

Signed call and put premium, bullish and bearish premium, one-minute buckets by moneyness, and how much of today's volume has a known side.

Parameters

symbolstringrequired
The ticker: SPY, SPX, NDX, AAPL …
series1default 0
1 adds the cumulative signed-premium path (net drift).
bucketsstringdefault all
Only the newest N one-minute buckets, 0 to 1440 (0: none, totals and classification only). The stream's flow family carries ?buckets=1 (the minute that changes) and its drift family ?buckets=0&series=1; the day's buckets are this GET once.

Response fields10

datedate
Trading date, Eastern.
totals.signed_call_premium, signed_put_premiumnumberUSD
Buys minus sells per side, today.
totals.bullish_premium, bearish_premiumnumberUSD
Call buys + put sells; call sells + put buys.
totals.net_premiumnumberUSD
bullish − bearish.
buckets[].ts, ts_mstimestamp
Start of the minute.
buckets[].spotnumberUSD
Spot during the minute.
buckets[].classified_tradesinteger
Prints with a known side in the minute.
buckets[].all, itm, atm, otmobject
signed_call_premium, signed_put_premium (USD) and signed_call_contracts, signed_put_contracts (contracts), buys minus sells, for all prints and by moneyness.
classification.classified_trades, unclassified_tradesinteger
Today.
classification.coveragenumberfraction
Share of today's volume with a known side.

Request

curl -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/symbols/SPY/flow"

Response

{"data": {"date": "2026-10-02","totals": {"signed_call_premium": -5321933,"signed_put_premium": 391354.0,"bullish_premium": 14905574,"bearish_premium": 20618861,"net_premium": -5713287},"buckets": [{"ts": "2026-10-02T13:30:00.000Z","spot": 770.12,"classified_trades": 14492,"all": {"signed_call_premium": -4105255,"signed_put_premium": 35111.0,…},"itm": {…}, "atm": {…}, "otm": {…}},…],"classification": {…}},"meta": {"symbol": "SPY", …}}

Flow leaders

GET/v1/flow/leaders

Underlyings or single contracts ranked by premium, volume, trades, sweeps or direction over a finished session or its week, each against its own baseline.

Parameters

datestring
A finished session, YYYY-MM-DD.
windowenumdefault day
day or week.
byenumdefault premium
premium, volume, trades, sweeps, bullish, bearish.
kindenumdefault underlyings
underlyings, or contracts with window=day.
limitintegerdefault 25
Rows, 1 to 200.

Response fields12

date, window, sessions[], by, kind, count
rows[].symbolstring
rows[].premium, call_premium, put_premiumnumberUSD
rows[].volume, call_volume, put_volume, tradesintegercontracts, prints
rows[].bullish_premium, bearish_premiumnumberUSD
rows[].imbalancenumberfraction
rows[].sweep_trades, sweep_premiuminteger, numberprints, USD
rows[].spotnumberUSD
rows[].premium_relative, volume_relativenumberfraction
rows[].baseline_sessionsintegersessions
contracts: rows[].contract, expiration, right, strikestring, date, string, numberUSD (strike)
meta.table_date, meta.table_sessionsdate, integer

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/flow/leaders" \-d "date=2026-10-16" \-d "limit=2"

Response

{"data": {"date": "2026-10-16","window": "day","by": "premium","kind": "underlyings","count": 2,"rows": [{"symbol": "SPX","premium": 27470807003.0,"volume": 7264302,"trades": 2102867,"bullish_premium": 16325118313.0,"bearish_premium": 9703965763.0,"imbalance": 0.2544,"spot": 7755.3501,"premium_relative": 1.5122,…},…]},"meta": {"as_of": "2026-10-18T13:53:02.554Z", "table_date": "2026-10-16", …}}

Sectors, breadth and unusual contracts

GET/v1/flow/sectors

GET/v1/flow/breadth

GET/v1/flow/unusual

Flow by sector against each sector's baseline, advancing and declining names by premium imbalance, and contracts trading a multiple of their usual volume.

Parameters

datestring
A finished session, YYYY-MM-DD.
thresholdnumber
Breadth: the imbalance beyond which a name advances or declines, 0 to 1.
min_volume_relativenumber
Unusual: how many times its usual volume a contract trades, at least.
min_volumeinteger
Unusual: contracts traded, at least.
limitintegerdefault 100
Unusual: rows, 1 to 500.

Fields of /flow/sectors8

date, count
rows[].sectorstring
rows[].symbolsintegernames
rows[].premium, call_premium, put_premium, bullish_premium, bearish_premiumnumberUSD
rows[].volumeintegercontracts
rows[].imbalancenumberfraction
rows[].baseline_symbolsintegernames
rows[].premium_relativenumberfraction

Fields of /flow/breadth6

date, threshold, symbols
advancing, declining, neutralintegernames
advance_decline_rationumberratio
premium, bullish_premium, bearish_premiumnumberUSD
imbalancenumberfraction
majors.{SPY,QQQ,IWM,DIA}.premium, .imbalancenumberUSD, fraction

Fields of /flow/unusual8

date, min_volume_relative, min_volume, count
rows[].contract, symbol, expiration, right, strikestring, string, date, string, numberUSD (strike)
rows[].volume, tradesintegercontracts, prints
rows[].premiumnumberUSD
rows[].imbalancenumberfraction
rows[].spotnumberUSD
rows[].baseline_sessionsintegersessions
rows[].volume_relativenumberfraction

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/flow/breadth" \-d "date=2026-10-16"

Response

{"data": {"date": "2026-10-16","threshold": 0.2,"symbols": 4777,"advancing": 1375,"declining": 1762,"neutral": 1484,"advance_decline_ratio": 0.7804,"premium": 57870338227.0,"imbalance": 0.1053,"majors": {"SPY": {"premium": 2818930657.0, "imbalance": -0.0304},"QQQ": {"premium": 3953707792.0, "imbalance": -0.0662},…}},"meta": {"as_of": "2026-10-18T13:53:03.468Z", "table_date": "2026-10-16", …}}

A symbol against its baseline

GET/v1/symbols/{symbol}/flow/baseline

GET/v1/symbols/{symbol}/flow/history

One session against the symbol's own baseline, by day and through the day; and its flow totals per session.

Parameters

symbolstringrequired
The ticker: SPY, SPX, NDX, AAPL …
datestring
A finished session, YYYY-MM-DD.
daysintegerdefault 20
flow/history: sessions, 1 to 60.

Fields of /flow/baseline8

symbol, date
baseline.sessionsintegersessions
sessionobject
slots[].timestringET
slots[].premium, bullish_premium, bearish_premiumnumberUSD
slots[].volume, tradesintegercontracts, prints
slots[].imbalancenumberfraction
slots[].premium_relativenumberfraction

Fields of /flow/history4

symbol, date, count
rows[].datedate
rows[].premium, call_premium, put_premiumnumberUSD
rows[].volume, call_volume, put_volumeintegercontracts

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/symbols/SPY/flow/history" \-d "date=2026-10-16"

Response

{"data": {"symbol": "SPY","date": "2026-10-16","count": 2,"rows": [{"date": "2026-10-15","premium": 2319046117.0,"volume": 14067216,"call_premium": 1189843173.0,"put_premium": 1129202944.0},{"date": "2026-10-16","premium": 2818930657.0,"volume": 16617125,"call_premium": 1197672186.0,"put_premium": 1621258471.0}]},"meta": {"symbol": "SPY", "table_date": "2026-10-16", …}}

Flow

Premium by side, name and sector.

Premium flow for one symbol

GET/v1/symbols/{symbol}/flow

Signed call and put premium, bullish and bearish premium, one-minute buckets by moneyness, and how much of today's volume has a known side.

Parameters

symbolstringrequired
The ticker: SPY, SPX, NDX, AAPL …
series1default 0
1 adds the cumulative signed-premium path (net drift).
bucketsstringdefault all
Only the newest N one-minute buckets, 0 to 1440 (0: none, totals and classification only). The stream's flow family carries ?buckets=1 (the minute that changes) and its drift family ?buckets=0&series=1; the day's buckets are this GET once.

Response fields10

datedate
Trading date, Eastern.
totals.signed_call_premium, signed_put_premiumnumberUSD
Buys minus sells per side, today.
totals.bullish_premium, bearish_premiumnumberUSD
Call buys + put sells; call sells + put buys.
totals.net_premiumnumberUSD
bullish − bearish.
buckets[].ts, ts_mstimestamp
Start of the minute.
buckets[].spotnumberUSD
Spot during the minute.
buckets[].classified_tradesinteger
Prints with a known side in the minute.
buckets[].all, itm, atm, otmobject
signed_call_premium, signed_put_premium (USD) and signed_call_contracts, signed_put_contracts (contracts), buys minus sells, for all prints and by moneyness.
classification.classified_trades, unclassified_tradesinteger
Today.
classification.coveragenumberfraction
Share of today's volume with a known side.

Request

curl -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/symbols/SPY/flow"

Response

{"data": {"date": "2026-10-02","totals": {"signed_call_premium": -5321933,"signed_put_premium": 391354.0,"bullish_premium": 14905574,"bearish_premium": 20618861,"net_premium": -5713287},"buckets": [{"ts": "2026-10-02T13:30:00.000Z","spot": 770.12,"classified_trades": 14492,"all": {"signed_call_premium": -4105255,"signed_put_premium": 35111.0,…},"itm": {…}, "atm": {…}, "otm": {…}},…],"classification": {…}},"meta": {"symbol": "SPY", …}}

Flow leaders

GET/v1/flow/leaders

Underlyings or single contracts ranked by premium, volume, trades, sweeps or direction over a finished session or its week, each against its own baseline.

Parameters

datestring
A finished session, YYYY-MM-DD.
windowenumdefault day
day or week.
byenumdefault premium
premium, volume, trades, sweeps, bullish, bearish.
kindenumdefault underlyings
underlyings, or contracts with window=day.
limitintegerdefault 25
Rows, 1 to 200.

Response fields12

date, window, sessions[], by, kind, count
rows[].symbolstring
rows[].premium, call_premium, put_premiumnumberUSD
rows[].volume, call_volume, put_volume, tradesintegercontracts, prints
rows[].bullish_premium, bearish_premiumnumberUSD
rows[].imbalancenumberfraction
rows[].sweep_trades, sweep_premiuminteger, numberprints, USD
rows[].spotnumberUSD
rows[].premium_relative, volume_relativenumberfraction
rows[].baseline_sessionsintegersessions
contracts: rows[].contract, expiration, right, strikestring, date, string, numberUSD (strike)
meta.table_date, meta.table_sessionsdate, integer

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/flow/leaders" \-d "date=2026-10-16" \-d "limit=2"

Response

{"data": {"date": "2026-10-16","window": "day","by": "premium","kind": "underlyings","count": 2,"rows": [{"symbol": "SPX","premium": 27470807003.0,"volume": 7264302,"trades": 2102867,"bullish_premium": 16325118313.0,"bearish_premium": 9703965763.0,"imbalance": 0.2544,"spot": 7755.3501,"premium_relative": 1.5122,…},…]},"meta": {"as_of": "2026-10-18T13:53:02.554Z", "table_date": "2026-10-16", …}}

Sectors, breadth and unusual contracts

GET/v1/flow/sectors

GET/v1/flow/breadth

GET/v1/flow/unusual

Flow by sector against each sector's baseline, advancing and declining names by premium imbalance, and contracts trading a multiple of their usual volume.

Parameters

datestring
A finished session, YYYY-MM-DD.
thresholdnumber
Breadth: the imbalance beyond which a name advances or declines, 0 to 1.
min_volume_relativenumber
Unusual: how many times its usual volume a contract trades, at least.
min_volumeinteger
Unusual: contracts traded, at least.
limitintegerdefault 100
Unusual: rows, 1 to 500.

Fields of /flow/sectors8

date, count
rows[].sectorstring
rows[].symbolsintegernames
rows[].premium, call_premium, put_premium, bullish_premium, bearish_premiumnumberUSD
rows[].volumeintegercontracts
rows[].imbalancenumberfraction
rows[].baseline_symbolsintegernames
rows[].premium_relativenumberfraction

Fields of /flow/breadth6

date, threshold, symbols
advancing, declining, neutralintegernames
advance_decline_rationumberratio
premium, bullish_premium, bearish_premiumnumberUSD
imbalancenumberfraction
majors.{SPY,QQQ,IWM,DIA}.premium, .imbalancenumberUSD, fraction

Fields of /flow/unusual8

date, min_volume_relative, min_volume, count
rows[].contract, symbol, expiration, right, strikestring, string, date, string, numberUSD (strike)
rows[].volume, tradesintegercontracts, prints
rows[].premiumnumberUSD
rows[].imbalancenumberfraction
rows[].spotnumberUSD
rows[].baseline_sessionsintegersessions
rows[].volume_relativenumberfraction

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/flow/breadth" \-d "date=2026-10-16"

Response

{"data": {"date": "2026-10-16","threshold": 0.2,"symbols": 4777,"advancing": 1375,"declining": 1762,"neutral": 1484,"advance_decline_ratio": 0.7804,"premium": 57870338227.0,"imbalance": 0.1053,"majors": {"SPY": {"premium": 2818930657.0, "imbalance": -0.0304},"QQQ": {"premium": 3953707792.0, "imbalance": -0.0662},…}},"meta": {"as_of": "2026-10-18T13:53:03.468Z", "table_date": "2026-10-16", …}}

A symbol against its baseline

GET/v1/symbols/{symbol}/flow/baseline

GET/v1/symbols/{symbol}/flow/history

One session against the symbol's own baseline, by day and through the day; and its flow totals per session.

Parameters

symbolstringrequired
The ticker: SPY, SPX, NDX, AAPL …
datestring
A finished session, YYYY-MM-DD.
daysintegerdefault 20
flow/history: sessions, 1 to 60.

Fields of /flow/baseline8

symbol, date
baseline.sessionsintegersessions
sessionobject
slots[].timestringET
slots[].premium, bullish_premium, bearish_premiumnumberUSD
slots[].volume, tradesintegercontracts, prints
slots[].imbalancenumberfraction
slots[].premium_relativenumberfraction

Fields of /flow/history4

symbol, date, count
rows[].datedate
rows[].premium, call_premium, put_premiumnumberUSD
rows[].volume, call_volume, put_volumeintegercontracts

Request

curl -G -H "Authorization: Bearer $DATAFIRST_API_KEY" \"https://api.datafirsttrading.com/v1/symbols/SPY/flow/history" \-d "date=2026-10-16"

Response

{"data": {"symbol": "SPY","date": "2026-10-16","count": 2,"rows": [{"date": "2026-10-15","premium": 2319046117.0,"volume": 14067216,"call_premium": 1189843173.0,"put_premium": 1129202944.0},{"date": "2026-10-16","premium": 2818930657.0,"volume": 16617125,"call_premium": 1197672186.0,"put_premium": 1621258471.0}]},"meta": {"symbol": "SPY", "table_date": "2026-10-16", …}}