GET /v2/flow/large-trades

Large option trades, newest first

flow_getLargeTrades

Large option trades (blocks, sweeps and multi-leg executions) from the options tape, newest first. Use it to follow large-trade activity for one underlying or across the market.

Query parameters

symbol string: Underlying to read, e.g. SPY. Omit for every underlying. Requests with an API key must send this or min_premium_usd.
session string ISO date: Exchange session (YYYY-MM-DD). Omit for every session still held (about the last 24 hours).
min_premium_usd string USD: Keep only events whose total premium is at least this many dollars. Applied before limit. Requests with an API key must send this or symbol.
limit integer · int32: Events per page: default 100, at most 200 (at most 100 with an API key). A larger value is clamped and reported in meta.limit_clamped.

Details

Each event lists its legs and carries its own coverage: observed_live while the session is being watched live, eod_reconciled once the end-of-day reconciliation has replaced it. A live event never claims complete: true.

Available with an API Pro key, or in the ITMatrixHQ apps on Pro. Both need a non-professional market-data declaration (POST /v2/account/classification).

Units

premium_usd is dollars; leg price, price_low and price_high are dollars per share; size and total_size are contracts.
Contract strike is in integer thousandths of a dollar (760000 = $760.00).
event_ts_ms and the coverage timestamps are epoch milliseconds.

Freshness

Events appear as they are detected during the session. The feed holds about the last 24 hours (meta.retention).

Limits

Requests with an API key must send symbol or min_premium_usd (otherwise 400 invalid_params) and receive at most 100 events per request.

Empty results

No qualifying trades is 200 with events: [].

Example

http

GET /v2/flow/large-trades?symbol=SPY&min_premium_usd=1000000&limit=1

json

{
  "data": {
    "events": [
      {
        "symbol": "SPY",
        "seq": 382,
        "coverage": {
          "status": "observed_live",
          "complete": false,
          "session_date": "2026-09-04",
          "observed_from_ms": 1788528600000,
          "observed_through_ms": 1788531723000,
          "registry_version": 1,
          "standard_multiplier_assumed": true
        },
        "update": {
          "kind": "big_trade",
          "event": {
            "event_id": "single_block:O:SPY260918P00760000:1788531722824:382",
            "event_kind": "single_block",
            "underlying": "SPY",
            "event_ts_ms": 1788531722824,
            "legs": [
              {
                "contract": {
                  "underlying": "SPY",
                  "expiry": "2026-09-18",
                  "right": "put",
                  "strike": 760000
                },
                "price": 3.25,
                "size": 32460,
                "premium_usd": 10549500.0,
                "exchange": 323,
                "conditions": [233],
                "event_ts_ms": 1788531722824,
                "sequence": 382,
                "side": "unknown",
                "multi_leg": false
              }
            ],
            "total_size": 32460,
            "premium_usd": 10549500.0,
            "price_low": 3.25,
            "price_high": 3.25,
            "side": "unknown",
            "multi_leg": false
          }
        }
      }
    ]
  },
  "meta": { "count": 1, "limit": 1, "retention": "intraday_24h" }
}

Response

Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →

200application/json

Bounded newest-first normalized large-trade events

object

A successful response: the payload consumers parse plus response metadata. data shapes are the platform types — never reshaped by the envelope.

data object required

events array<FlowLargeTradeEvent> required

coverage object required

Completeness metadata carried by every flow payload. Live values never claim to be a complete session; the nightly flat-file replacement is the only producer allowed to stamp EodReconciled and complete = true.

complete boolean required

observed_from_ms integer · int64 required epoch ms

observed_through_ms integer · int64 required epoch ms

registry_version integer · int32 required

session_date string · date required ISO date

US-Eastern exchange session this payload belongs to. Consumers must never merge cumulative flow across this boundary.

standard_multiplier_assumed boolean required

OPRA does not carry adjusted-contract deliverables on each print. true means premium used the standard 100-share multiplier.

status string required

One of observed_liveeod_reconciled

seq integer · int64 required

symbol string required

update one of required

variant 1 object

event object required

Normalized large-trade wire shape. A single block has one leg; sweeps and complex executions have multiple legs, so API/frontend consumers need no variant-specific extraction logic.

event_id string required

event_kind string required

One of single_blocksweepmulti_leg

event_ts_ms integer · int64 required epoch ms

legs array<FlowTradeLegMsg> required

multi_leg boolean required

premium_usd number · double required USD

price_high number · double required

price_low number · double required

side string required

One of buy_inferredsell_inferredneutralunknown

total_size integer · int64 required

underlying string required

kind string required

One of big_trade

meta object required

Response metadata.

caps object nullable

meta.caps — the entitlement caps that shaped this response. applied lists the caps that actually changed it (for example range_clamped).

applied array<string> required

Which caps actually shaped this response (e.g. range_clamped). Empty = nothing was clamped.

darkpool boolean nullable

Whether this account can use Off-Exchange in the site.

flow boolean nullable

Whether the OPRA option-flow capability (flow) is granted to this principal in the app: site Pro plus a CBOE non-professional attestation (never on an itm_ key). Emitted explicitly — true and false — by the account endpoints, so the app reads the grant instead of inferring it from tier and attestation; absent on routes that do not report it.

gexDepth string nullable

GEX data depth when the route reports it. Camel-cased to match the browser capability bundle; absent on unrelated routes.

tier string required

The tier the request was served under.

cursor string nullable

Opaque continuation cursor (pass back as ?cursor=); absent when there is nothing more to read.

plane string nullable

Which serving tier answered the read (meta.plane). Informational provenance: treat it as an opaque label, because new values may appear.

Errors

Every error is the JSON error envelope; branch on error.code.

Status	Meaning
400	`invalid_params` — invalid filter, or a keyed request omitted both `symbol` and `min_premium_usd`
401	`unauthenticated`
403	`not_entitled_tier` — not an app principal, or below site `pro`; `attestation_required` — Pro without a CBOE attestation
404	`not_found` — filtered symbol is not registered

Request

curl -sS -G "https://api.itmatrixhq.com/v2/flow/large-trades" \
  -H "Authorization: Bearer $ITM_API_KEY" \
  -d "symbol=SPY" \
  -d "limit=25"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/flow/large-trades",
    params={"symbol": "SPY", "limit": 25},
    headers={"Authorization": f"Bearer {os.environ['ITM_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.flow.large_trades(symbol="SPY", limit=25)
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/flow/large-trades");
url.search = new URLSearchParams({ symbol: "SPY", limit: "25" }).toString();

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ITM_API_KEY}` },
});
console.log(response.status, await response.json());

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
const result = await client.flow.largeTrades({ symbol: "SPY", limit: 25 });
console.log(result.status, result.data);