Pro API Documentation

null is not zero

null means not observed or not computed. 0 means a measured zero. They are never used interchangeably, and a nullable numeric is never disguised as 0. Treat every price, Greek and IV field as nullable — enrichment is incomplete on a small share of rows (about 5% of live tape rows carry a null implied_volatility), and one null will poison a downstream average if you coerce it.

Units, scales and signs

• Implied volatility is decimal, not percent — 0.1238 is 12.38%.
• Ranks and percentiles are 0–1, not 0–100.
• Premium and notional are US dollars, already multiplied by contract size.
• n counts observations in a window, not calendar days. Endpoints reporting n also report the from/to dates of that sample.
• Signed premium follows the aggressor: BUY (at ask) is + premium paid, SELL (at bid) is - premium received. Puts are not sign-flipped anywhere in the API.

How a direction was determined — three different things

Every direction-bearing field declares its basis, because these are not interchangeable and only one of them is reported by an exchange:

• aggressor_nbbo — inferred from where the print landed against the NBBO. Exchanges do not publish aggressor side, so this is our classification; direction_confidence (0–1) says how strongly.
• nbbo_location_proxy (dark pool) — a proxy. It does not identify an institution and does not prove buyer or seller intent.
• Multi-leg membership is genuinely exchange-confirmed (OPRA condition codes 232–247), but the structure name (vertical, calendar, butterfly…) is our geometric classification of the legs, not an exchange label.

What is calibrated, and what is not

Most scores on this API are descriptive statistics, not validated predictors. Where an endpoint has never been tested against subsequent price movement it says so in its own payload — Tide, for example, carries basis.calibration: "none". Do not read a confidence field as a calibrated probability unless the endpoint states that it is.

The one directional construction we have validated out-of-sample is published: Option Flow Predicts Returns — Call Imbalance in OTM institutional blocks, OOS Sharpe 1.6–1.8 over a 416-session holdout. In the same study, composite directional signals and buy-side-only pressure were eliminated entirely, and put imbalance reversed. Treat that as the evidence bar.

Sessions and timestamps

session is the US market session a payload describes (YYYY-MM-DD, US Eastern trading day). Endpoints that compute rather than merely read also return as_of (the newest observation actually included — real data freshness) and computed_at (when the response was assembled). On a quiet tape those differ noticeably, and staleness should be judged from as_of. Where present, finality distinguishes a provisional session still accumulating from a settled final one.

A "current" endpoint returns the latest session that has data — which after the close, at a weekend, or on a holiday is the last completed session, not today. Confluence on the returned session value rather than assuming two endpoints describe the same day.

Quota model

Four independent budgets, not one. A request can be refused by any of them:

The per-minute window is fixed, not rolling: the counter is keyed to the wall-clock minute, and X-RateLimit-Reset is the unix second at which it rolls. Honour Retry-After when present — it takes precedence.

Score methodology — net_delta_last and directional_score

Both are weighted constructions, not raw sums, so neither can be reproduced from a field name alone.

/v1/flow/current — rankings[].net_delta_last

Signed dollar-delta of the most recent 5-minute cluster only (not cumulative for the session). Per order:

delta_$ = option_delta
        x spot
        x contracts            (order-level total_contracts)
        x multiplier           (shares_per_contract, default 100)
        x dir_score            (+conf buy / -conf sell / +conf x 0.25 neutral)
        x close_mult           (0.40 likely-closing / 0.70 uncertain / 1.00 default)
        x dte_mult             (0.60 if DTE<=1 / 0.85 if DTE<=5 / 1.00 otherwise)

net_delta_last = sum(delta_$) over the latest 5-minute cluster

So yes — option delta, total contracts and the 100 multiplier are all applied. But three further weights are applied that the field name does not imply: dir_score scales by our direction confidence and carries the sign, close_mult discounts trades inferred to be closing, and dte_mult discounts short-dated ones. Unit is USD of delta exposure, signed (positive = net long delta bought). It is a confidence-weighted, discounted dollar delta — not reproducible from delta x contracts x 100. The same six factors build net_gamma_last (spot squared), net_vega_last and net_theta_last (no spot term).

/v1/directional/current — the four pressures and directional_score

Each pressure is the summed notional (USD) of that session's large orders in that bucket, and the values are returned already signed by directional meaning:

call_buy_pressure    positive   (bullish)
call_sell_pressure   negative   (bearish)
put_buy_pressure     negative   (bearish)
put_sell_pressure    positive   (bullish)

directional_score = call_buy + call_sell + put_buy + put_sell
                  = (CB + PS) - (CS + PB)   in unsigned terms

imbalance_score   = (|CB| - |PB|) / (|CB| + |PB|)     in [-1, +1]

So yes, directional_score is the plain sum of the four fields as returned — because the sign is already baked into each one. Note this is the put-flipped directional construction (buying a put is bearish, selling one is bullish), which is what distinguishes it from Tide's net_premium, an accounting measure that does not flip puts.

imbalance_score uses absolute call and put buy pressure, so it measures call-vs-put concentration, not direction. Both are raw notional — no volatility adjustment, no cross-sectional normalisation — so magnitudes are not comparable across tickers; a mega-cap will dominate a small-cap on size alone.

A missing ticker does not mean "no evidence"

/v1/directional/current truncates by row order, so absence is not a statement about the ticker. Two caps apply: your max_display (10–500), and a server-side ceiling of 500 rows. Compare tickers_count against the length of data to detect truncation — but note tickers_count is itself capped at 500, and the echoed max_display reflects the cache build parameter rather than your request.

There is no batch parameter for an explicit ticker list on either endpoint. For a known set, use /v1/flow/{session}/{ticker} or /v1/directional/{ticker}/history per name, or pull the whole session once via /v1/directional/{session} and filter client-side — one request rather than N.

Changelog

Dated, newest first. Methodology changes are listed separately from additive field changes so you can tell which require re-reading numbers.

Known gaps

Rather than leave you to find these during an integration, the current limitations of this reference:

• No machine-readable OpenAPI document yet. Response schemas are documented per endpoint here but are not downloadable or CI-validated.
• The daily request budget is enforced but not yet surfaced as a response header — only the per-minute budget is.
• GET /v1/quotes/watchlist reports the distinct-additions limit but not how many you have already used today.
• /v1/screener returns session: "latest" rather than the resolved date other endpoints return.
• Multi-leg legs expose expiration as MM/DD with no year and carry no dte; parse the OCC symbol for an unambiguous date.
• Derived-score methodology (intent, directional) is not yet published at the level needed to reproduce a value independently.