{"uid":"cap_jC5ATDh5BKYJTJwQQmSBt","slug":"bullflow-historical-options-flow-a32ef678","name":"Bullflow Historical Options Flow","description":"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.","url":"https://api.bullflow.io/v1/data/historicalOptionsFlow?utm_source=zero.xyz","method":"GET","headers":{},"bodySchema":{"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","MULTI"],"type":"string"},"maxPremium":{"type":"number","minimum":0},"minPremium":{"type":"number","minimum":0},"optionType":{"enum":["C","P"],"type":"string"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["from","to","timezone","ticker","symbol","optionType","tradeType","side","minPremium","maxPremium","minSize","maxSize","minScore","count","limit","hasMore","nextCursor","rows"],"properties":{"to":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"from":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"rows":{"type":"array","items":{"type":"object","required":["id","tradeDate","timestamp","symbol","ticker","optionType","expirationDate","strikePrice","premium","tradePrice","tradeSize","tradeType","side","spotPrice","currentBid","currentAsk","currentVolume","openInterest","impliedVolatility","sigScore","delta","gamma","theta","vega","rho"],"properties":{"id":{"type":"string"},"rho":{"type":["number","null"]},"side":{"type":["string","null"]},"vega":{"type":["number","null"]},"delta":{"type":["number","null"]},"gamma":{"type":["number","null"]},"theta":{"type":["number","null"]},"symbol":{"type":["string","null"]},"ticker":{"type":["string","null"]},"premium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"sigScore":{"type":["number","null"],"description":"Trade unusualness score, from 0 to 1."},"spotPrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"timestamp":{"type":"number","description":"Trade Unix timestamp in seconds."},"tradeDate":{"type":"string","description":"Trading date in YYYY-MM-DD format."},"tradeSize":{"anyOf":[{"type":"integer","maximum":9007199254740991,"minimum":0},{"type":"null"}]},"tradeType":{"type":["string","null"]},"currentAsk":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"currentBid":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"optionType":{"anyOf":[{"enum":["C","P"],"type":"string"},{"type":"null"}]},"tradePrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"strikePrice":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"openInterest":{"anyOf":[{"type":"integer","maximum":9007199254740991,"minimum":0},{"type":"null"}]},"currentVolume":{"anyOf":[{"type":"integer","maximum":9007199254740991,"minimum":0},{"type":"null"}]},"expirationDate":{"anyOf":[{"type":"string","description":"Trading date in YYYY-MM-DD format."},{"type":"null"}]},"impliedVolatility":{"type":["number","null"],"description":"Implied volatility in percent."}}},"description":"One page of recorded options trades. Unavailable values are null."},"side":{"anyOf":[{"enum":["Ask","Above Ask","Mid","Bid","Below Bid"],"type":"string"},{"type":"null"}]},"count":{"type":"integer","maximum":9007199254740991,"minimum":0},"limit":{"type":"integer","maximum":9007199254740991,"minimum":0},"symbol":{"type":["string","null"]},"ticker":{"type":["string","null"]},"hasMore":{"type":"boolean"},"maxSize":{"anyOf":[{"type":"integer","maximum":9007199254740991,"minimum":0},{"type":"null"}]},"minSize":{"anyOf":[{"type":"integer","maximum":9007199254740991,"minimum":0},{"type":"null"}]},"minScore":{"type":["number","null"]},"timezone":{"type":"string","const":"America/New_York"},"tradeType":{"anyOf":[{"enum":["SWEEP","BLOCK","MULTI"],"type":"string"},{"type":"null"}]},"maxPremium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"minPremium":{"anyOf":[{"type":"number","description":"Amount in US dollars."},{"type":"null"}]},"nextCursor":{"type":["string","null"]},"optionType":{"anyOf":[{"enum":["C","P"],"type":"string"},{"type":"null"}]}}}}}}},"responseSchema":{"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}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.01","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.01/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.01","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_dGcLwCYTckdq5vDbxH88R","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.01","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Retrieves paginated historical unusual options flow and dark pool trade records filtered by ticker, date range, trade type, premium, and other criteria","exampleAgentPrompt":"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.","exampleUseCases":[{"title":"Earnings options sweep research","prompt":"Show me all unusual options sweeps on NVDA for the 5 days before their last earnings — calls only, traded at the ask, with at least $250,000 in premium. I want to see if there was any smart money positioning."},{"title":"Dark pool block trade screening","prompt":"Pull historical block trades from Bullflow for SPY and QQQ between July 1 and July 15, 2024, with a minimum premium of $1 million — I want to see the biggest institutional options bets during that window."},{"title":"Bearish put flow monitoring","prompt":"Get me all put sweeps on TSLA that traded at or above the ask for the past two weeks, sorted by premium, so I can see if there was unusual bearish activity building up."}],"resultDescription":"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.","failureModes":["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"],"whenToPreferThis":"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.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-29T07:00:18.312Z","isFirstParty":false,"canonicalSlug":"bullflow-historical-options-flow-a32ef678"}