OptionWhales Options Flow API

The options-flow API from OptionWhales — 14 operation(s) for options-flow.

GitHub OpenAPI

Operations 14

GET /v1/options-flow/health Flow Health #
GET /v1/options-flow/sessions Flow Sessions #
GET /v1/options-flow/tickers Flow Tickers #
GET /v1/options-flow/multi-leg Flow Multi Leg #
GET /v1/options-flow/multi-leg/{package_id} Flow Multi Leg One #
GET /v1/options-flow/tape Flow Tape #
GET /v1/options-flow/contract/{occ}/summary Flow Contract Summary #
GET /v1/options-flow/contract/{occ} Flow Contract #
GET /v1/options-flow/ticker/{ticker}/strikes Flow Ticker Strikes #
GET /v1/options-flow/ticker/{ticker}/expiries Flow Ticker Expiries #
GET /v1/options-flow/ticker/{ticker}/ticks Flow Ticker Ticks #
GET /v1/options-flow/ticker/{ticker}/intraday Flow Ticker Intraday #
GET /v1/options-flow/ticker/{ticker}/greek-flow Flow Ticker Greek Flow #
GET /v1/options-flow/ticker/{ticker}/contracts Flow Ticker Contracts #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/optionwhales-io:optionwhales-io-options-flow-api"
All apis
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.

Get an API 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 Specification

optionwhales-io-options-flow-api-openapi.yml Raw ↑
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