# Bullflow Historical Options Flow

> Bullflow Historical Options Flow is a paid API for AI agents from api.bullflow.io, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-29).

Retrieves paginated historical unusual options flow and dark pool trade records filtered by ticker, date range, trade type, premium, and other criteria

## Facts

- Endpoint: GET https://api.bullflow.io/v1/data/historicalOptionsFlow?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/bullflow-historical-options-flow-a32ef678
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_jC5ATDh5BKYJTJwQQmSBt

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability bullflow-historical-options-flow-a32ef678
```

Example prompt: Pull historical unusual options flow for SPY from 2024-06-01 to 2024-06-15, filtering to call sweeps only that traded at the ask with a minimum premium of $500,000 — give me up to 500 records.

## When to prefer this

Use this endpoint when you need historical (not real-time) options flow records with flexible filtering by ticker, date range, trade type, side, and premium. It is the right choice for backtesting unusual options signals, researching smart money positioning ahead of events, or scanning for specific large trades on past dates. Prefer this over real-time endpoints when investigating past market activity or building historical datasets up to 30-day windows.

## Known failure modes

- Invalid date format (must be YYYY-MM-DD) returns a validation error
- Supplying both 'date' and 'from'/'to' simultaneously causes a schema conflict error
- Date range exceeding 30 calendar days returns an error
- Invalid enum value for side, tradeType, or optionType returns a 400 bad request
- No data available for requested date (weekend or market holiday) returns empty rows array
- Invalid cursor token results in a pagination error or empty response
- Rate limiting or unpaid x402 payment header returns a 402 Payment Required

## How this service works

Bullflow.io is a real-time unusual options flow and dark pool tracker with advanced tools to view, filter, and analyze market activity as it happens.

## Output

Returns a paginated JSON object containing an array of historical options flow records matching the supplied filters, along with the total count, applied filter echoes (ticker, dates, side, trade type, option type, premium range, size range, score), a boolean hasMore flag, and a nextCursor string for fetching the next page.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "oneOf": [
      {
       "not": {
        "anyOf": [
         {
          "required": [
           "from"
          ]
         },
         {
          "required": [
           "to"
          ]
         }
        ]
       },
       "required": [
        "date"
       ]
      },
      {
       "not": {
        "required": [
         "date"
        ]
       },
       "required": [
        "from",
        "to"
       ]
      }
     ],
     "required": [],
     "properties": {
      "to": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Inclusive end date. Supply with from; maximum range is 30 calendar days."
      },
      "date": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Trading date in YYYY-MM-DD format."
      },
      "from": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Inclusive start date. Supply with to; do not combine with date."
      },
      "side": {
       "enum": [
        "Ask",
        "Above Ask",
        "Mid",
        "Bid",
        "Below Bid"
       ],
       "type": "string"
      },
      "limit": {
       "type": "integer",
       "default": 500,
       "maximum": 5000,
       "minimum": 1,
       "description": "Maximum number of records in this page."
      },
      "cursor": {
       "type": "string",
       "description": "Use nextCursor from the previous page with the same filters."
      },
      "symbol": {
       "type": "string",
       "description": "Exact option contract symbol."
      },
      "ticker": {
       "type": "string",
       "examples": [
        "SPY"
       ],
       "description": "Underlying stock, ETF, or supported index ticker."
      },
      "maxSize": {
       "type": "integer",
       "minimum": 0
      },
      "minSize": {
       "type": "integer",
       "minimum": 0
      },
      "minScore": {
       "type": "number",
       "maximum": 1,
       "minimum": 0
      },
      "tradeType": {
       "enum": [
        "SWEEP",
        "BLOCK",
 
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "to": "2026-10-14",
  "from": "2026-10-14",
  "rows": [],
  "side": null,
  "count": 0,
  "limit": 10,
  "symbol": null,
  "ticker": "SPY",
  "hasMore": false,
  "maxSize": null,
  "minSize": null,
  "minScore": null,
  "timezone": "America/New_York",
  "tradeType": null,
  "maxPremium": null,
  "minPremium": null,
  "nextCursor": null,
  "optionType": null
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/bullflow-historical-options-flow-a32ef678/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.bullflow.io](https://www.zero.xyz/host/api.bullflow.io/llms.txt)