OptionWhales Options Flow API
The options-flow API from OptionWhales — 14 operation(s) for options-flow.
The options-flow API from OptionWhales — 14 operation(s) for options-flow.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/optionwhales-io:optionwhales-io-options-flow-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: OptionWhales Pro Options Flow API
description: Premium API for intent flow, momentum, abnormal trades, earnings intelligence, economic events, directional scores, GEX, dark pool, implied-volatility analytics, open interest, and an MCP server for AI agents
version: 1.2.0
tags:
- name: options-flow
paths:
/v1/options-flow/health:
get:
tags:
- options-flow
summary: Flow Health
description: Feature availability (any tier — lets a key be smoke-tested).
operationId: flow_health_v1_options_flow_health_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/v1/options-flow/sessions:
get:
tags:
- options-flow
summary: Flow Sessions
description: Available sessions + the recording threshold.
operationId: flow_sessions_v1_options_flow_sessions_get
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
/v1/options-flow/tickers:
get:
tags:
- options-flow
summary: Flow Tickers
description: 'Underlyings with recorded large-order flow in a session.
NOT the listed-options universe — this is "what printed size", which is the
question the rest of this family can act on. The response `basis` says so.'
operationId: flow_tickers_v1_options_flow_tickers_get
parameters:
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: limit
in: query
required: false
schema:
type: integer
maximum: 20000
minimum: 1
default: 10000
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/multi-leg:
get:
tags:
- options-flow
summary: Flow Multi Leg
description: 'Reconstructed multi-leg strategies — verticals, calendars, condors and
friends — with net premium, net delta and a directional label.
Detection is structural, not heuristic: legs are gated on the OPRA multi-leg
condition codes (232-247) and matched within a ~100ms coincidence window, so
a package is a genuine complex order rather than trades that merely landed
close together.'
operationId: flow_multi_leg_v1_options_flow_multi_leg_get
parameters:
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: ticker
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Ticker
- name: structure
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: vertical_spread | ratio_spread | diagonal_spread | calendar_spread | straddle | strangle | butterfly | condor | iron_condor | iron_butterfly
title: Structure
description: vertical_spread | ratio_spread | diagonal_spread | calendar_spread | straddle | strangle | butterfly | condor | iron_condor | iron_butterfly
- name: direction
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: bullish | bearish | neutral
title: Direction
description: bullish | bearish | neutral
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
description: Absolute net-premium floor
default: 0.0
title: Min Premium
description: Absolute net-premium floor
- name: min_legs
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 2
- type: 'null'
title: Min Legs
- name: max_legs
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 2
- type: 'null'
title: Max Legs
- name: limit
in: query
required: false
schema:
type: integer
maximum: 1000
minimum: 1
default: 100
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/multi-leg/{package_id}:
get:
tags:
- options-flow
summary: Flow Multi Leg One
description: One strategy and its individual legs.
operationId: flow_multi_leg_one_v1_options_flow_multi_leg__package_id__get
parameters:
- name: package_id
in: path
required: true
schema:
type: string
title: Package Id
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: ticker
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Narrows the scan when known
title: Ticker
description: Narrows the scan when known
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/tape:
get:
tags:
- options-flow
summary: Flow Tape
description: 'Filtered, cursor-paginated recorded-order tape, newest first.
Historical sessions require a ``ticker`` or ``occ`` filter — the session index
is sorted by ticker, so an unfiltered historical read is a bulk export.'
operationId: flow_tape_v1_options_flow_tape_get
parameters:
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Session YYYY-MM-DD; default live
title: Session
description: Session YYYY-MM-DD; default live
- name: ticker
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: Underlying(s); required for historical
title: Ticker
description: Underlying(s); required for historical
- name: occ
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
- type: 'null'
description: OCC contract symbol(s)
title: Occ
description: OCC contract symbol(s)
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: call | put
title: Type
description: call | put
- name: direction
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: buy | sell
title: Direction
description: buy | sell
- name: order_type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Order Type
- name: min_contracts
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Min Contracts
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
- name: min_confidence
in: query
required: false
schema:
anyOf:
- type: number
maximum: 1.0
minimum: 0.0
- type: 'null'
title: Min Confidence
- name: dte_min
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Min
- name: dte_max
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Max
- name: strike_min
in: query
required: false
schema:
anyOf:
- type: number
minimum: 0.0
- type: 'null'
title: Strike Min
- name: strike_max
in: query
required: false
schema:
anyOf:
- type: number
minimum: 0.0
- type: 'null'
title: Strike Max
- name: expiry_from
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Expiry From
- name: expiry_to
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Expiry To
- name: older_than
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Cursor — rows strictly older
title: Older Than
description: Cursor — rows strictly older
- name: newer_than
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Newer Than
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
default: 100
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/contract/{occ}/summary:
get:
tags:
- options-flow
summary: Flow Contract Summary
description: 'Aggregate flow for one contract — buy/sell split, VWAP, counts.
Undelayed and off the row budget: one row per contract is not reproducible
into a competing tape, so none of the tape controls apply.'
operationId: flow_contract_summary_v1_options_flow_contract__occ__summary_get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/contract/{occ}:
get:
tags:
- options-flow
summary: Flow Contract
description: Recorded orders on ONE contract, newest first.
operationId: flow_contract_v1_options_flow_contract__occ__get
parameters:
- name: occ
in: path
required: true
schema:
type: string
title: Occ
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: direction
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Direction
- name: min_contracts
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
title: Min Contracts
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
- name: older_than
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Older Than
- name: newer_than
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Newer Than
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
default: 100
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/strikes:
get:
tags:
- options-flow
summary: Flow Ticker Strikes
description: Large-order flow per strike, call/put split, with buy/sell premium.
operationId: flow_ticker_strikes_v1_options_flow_ticker__ticker__strikes_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: call | put
title: Type
description: call | put
- name: dte_min
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Min
- name: dte_max
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Max
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
- name: limit
in: query
required: false
schema:
type: integer
maximum: 2000
minimum: 1
default: 200
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/expiries:
get:
tags:
- options-flow
summary: Flow Ticker Expiries
description: Large-order flow per expiry, call/put split, with DTE.
operationId: flow_ticker_expiries_v1_options_flow_ticker__ticker__expiries_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: call | put
title: Type
description: call | put
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
- name: limit
in: query
required: false
schema:
type: integer
maximum: 2000
minimum: 1
default: 200
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/ticks:
get:
tags:
- options-flow
summary: Flow Ticker Ticks
description: Net call/put premium per time bucket, plus the running cumulative series.
operationId: flow_ticker_ticks_v1_options_flow_ticker__ticker__ticks_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: interval
in: query
required: false
schema:
type: integer
description: 'Bucket minutes: 1|5|15|30|60'
default: 1
title: Interval
description: 'Bucket minutes: 1|5|15|30|60'
- name: dte_min
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Min
- name: dte_max
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Max
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/intraday:
get:
tags:
- options-flow
summary: Flow Ticker Intraday
description: Flow per (strike, time bucket), bounded to the busiest strikes by premium.
operationId: flow_ticker_intraday_v1_options_flow_ticker__ticker__intraday_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: interval
in: query
required: false
schema:
type: integer
description: 'Bucket minutes: 1|5|15|30|60'
default: 5
title: Interval
description: 'Bucket minutes: 1|5|15|30|60'
- name: top_strikes
in: query
required: false
schema:
type: integer
maximum: 200
minimum: 1
default: 20
title: Top Strikes
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: call | put
title: Type
description: call | put
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/greek-flow:
get:
tags:
- options-flow
summary: Flow Ticker Greek Flow
description: 'Signed DELTA flow per time bucket — directional exposure transacted.
Delta only. Our per-order schema carries delta but not vega, and estimating
vega from IV and DTE would be a model output wearing the name of a
measurement, so the field is omitted rather than approximated.'
operationId: flow_ticker_greek_flow_v1_options_flow_ticker__ticker__greek_flow_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: interval
in: query
required: false
schema:
type: integer
description: 'Bucket minutes: 1|5|15|30|60'
default: 1
title: Interval
description: 'Bucket minutes: 1|5|15|30|60'
- name: dte_min
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Min
- name: dte_max
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Max
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/options-flow/ticker/{ticker}/contracts:
get:
tags:
- options-flow
summary: Flow Ticker Contracts
description: 'Per-contract roll-up for one underlying, ranked.
Aggregate like ``/summary`` — undelayed and off the row budget.'
operationId: flow_ticker_contracts_v1_options_flow_ticker__ticker__contracts_get
parameters:
- name: ticker
in: path
required: true
schema:
type: string
title: Ticker
- name: session
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Session
- name: type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Type
- name: dte_min
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Min
- name: dte_max
in: query
required: false
schema:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Dte Max
- name: min_premium
in: query
required: false
schema:
type: number
minimum: 0.0
default: 0.0
title: Min Premium
- name: sort
in: query
required: false
schema:
type: string
description: premium|contracts|orders|net_premium|notional|trades
default: premium
title: Sort
description: premium|contracts|orders|net_premium|notional|trades
- name: limit
in: query
required: false
schema:
type: integer
maximum: 2000
minimum: 1
default: 100
title: Limit
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError