Options Block Trades API - Large Print Detection | FlashAlpha
FlashAlpha FlashAlpha
  1. Block Trades

Options Block Trades API

Large option trades across all contracts for an underlying, newest first, filtered by minimum contract size.

Endpoint

GET /v1/flow/options/{symbol}/blocks
Auth required (X-Api-Key) Rate Limited: Yes Plan: Alpha+

Parameters

Name In Type Required Default Description
symbol path string required - Underlying symbol
minSize query integer 100 Minimum contract size. Non-numeric values return a 400 problem-details body. Values below 1 are treated as 1.
expiry query date - Filter to a single expiration cycle, yyyy-MM-dd. Omit to include all expiries. 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/options/SPY/blocks?minSize=250"
import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/flow/options/SPY/blocks",
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
resp.raise_for_status()
data = resp.json()
print(f"{data['count']} blocks at minSize {data['minSize']}")
const resp = await fetch(
  "https://lab.flashalpha.com/v1/flow/options/SPY/blocks",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const data = await resp.json();
console.log(data.count + " blocks at minSize " + data.minSize);

Try it live

Runs on live market data and uses 1 request from your daily quota.

GET
View response ↓

Response

{
  "symbol": "SPY",
  "expiry": null,
  "minSize": 250,
  "count": 7,
  "blocks": [
    {
      "ts": "2026-10-30T13:45:37.643Z",
      "expiry": "2026-10-30",
      "strike": 757,
      "right": "P",
      "price": 0.79,
      "size": 282,
      "side": "buy",
      "vendorSide": "none"
    },
    {
      "ts": "2026-10-30T13:45:22.456Z",
      "expiry": "2026-10-30",
      "strike": 750,
      "right": "P",
      "price": 0.12,
      "size": 407,
      "side": "buy",
      "vendorSide": "none"
    }
  ],
  "endpoint_version": "2026.09.30",
  "data_as_of": {
    "node": "fa4",
    "equity_feed": "2026-10-30T13:45:50.282Z",
    "equity_options_feed": "2026-10-30T13:45:48Z",
    "index_feed": "2026-10-30T13:45:49.521Z",
    "index_options_feed": "2026-10-30T13:45:45Z",
    "futures_feed": "2026-10-30T13:45:42.97Z",
    "futures_options_feed": "2026-10-30T13:45:43.095Z",
    "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.

Response Fields

Field Type Description
symbolstringUppercase underlying symbol
minSizeintegerMinimum block size applied
countintegerNumber of block trades returned
blocks[]arrayBlock rows: ts, expiry, strike, right, price, size, side
expirystring | nullEcho of the ?expiry= filter, or null when no filter was applied
blocks[].tsstringTimestamp of the trade (UTC)
blocks[].strikenumberStrike price
blocks[].rightstringBlocks: right
blocks[].pricenumberBlocks: price
blocks[].sizenumberBlocks: size
blocks[].sidestringBlocks: side
blocks[].vendorSidestringBlocks: vendor side
blocks[].expirystringThe contract's own expiry date (yyyy-MM-dd, never null)
endpoint_version, data_as_ofstring, objectResponse envelope, see Response envelope.

Errors

Status Error When
400invalid_expiryexpiry 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.
403tier_restrictedYour plan is below Alpha. The body includes current_plan and required_plan.
429Quota exceededDaily quota used up. Retry-After gives the seconds until the reset at 00:00 UTC. Rejected requests (including 403) count toward the quota.
502-Upstream flow data source unavailable.

About

Filters the option tape to only prints at or above minSize contracts. Default is 100 contracts but you can raise it for institutional-only filtering. Returns rows in the same shape as the recent feed minus instrument id, bid, and ask.

Common Use Cases

  • Track institutional-only flow - raise minSize to 500+ and watch blocks[] to surface only large single-ticket prints worth reacting to
  • Detect multi-leg sweeps - cluster blocks[] by ts across strikes and expiries to identify a single sweep routed across venues
  • Read directional intent - combine side with right (e.g. buy calls vs buy puts) to tell bullish bets from hedges or bearish positioning
  • Score conviction by notional - multiply size by price on each block to rank prints by dollars committed, not just contract count
  • Spot event positioning - scan large prints on specific expiry legs into earnings or macro catalysts
  • Build a day sentiment overlay - tally buy-side versus sell-side size across blocks to gauge net institutional pressure

Related reading

Complementary endpoints

Ready to build with FlashAlpha?

Get your free API key and start pulling live options data in 60 seconds.

No credit card required Setup in 60 seconds Secure & reliable
Get Free API Key Try Playground