API · v1

OptionsBell REST API

Programmatic access to unusual options activity, derived metrics, per-symbol flow, and aggregated sentiment across 7,000+ US-listed stocks. JSON over HTTPS, key-authenticated, rate-limited per tier.

JSON over HTTPSX-API-Key authv1 stableUsing Claude? Connect via MCP →

Authentication

All requests authenticate via the X-API-Key header. Generate a key in your account settings - an active subscription is required.

curl https://optionsbell.com/api/v1/options-flow/unusual \
  -H "X-API-Key: sms_xxxxxxxxxxxxxxxx"

Rate limits & usage cap

Rate limits are tier-based and enforced per API key. Responses include X-RateLimit-* headers so you can pace your client.

1,000 Monthly Active User (MAU) cap. A Pro subscription includes a limited license to redistribute API output inside your own products, apps and agents up to 1,000 MAU. Anything beyond that requires an enterprise agreement — reach out at [email protected] for a quote. Full definitions and audit rights are in our Terms.

Tier	Per minute	Per day
Pro	30	2,000

Endpoints

GET/api/v1/options-flow/unusual

Latest unusual options activity scan across the covered universe of 7,000+ US-listed stocks. Same dataset that powers the email alerts. Filter by symbol, contract type, minimum Vol/OI, premium, IV, and days-to-expiry.

/api/v1/options-flow/unusual?symbols=AAPL,NVDA&type=c&min_voloi=5&min_premium=250000&limit=300

GET/api/v1/options-flow/:symbol

Per-symbol unusual options activity - every contract on a single ticker that passed the unusual filter during the latest scan, sorted by Vol/OI. Drop-in for a research dashboard, watchlist monitor, or custom integration.

/api/v1/options-flow/:symbol/AAPL?limit=100

GET/api/v1/options-flow/top

Top prints of a trading day, ranked by estimated premium - the biggest bets view that also powers the alert emails. Defaults to the latest day; scope by date, side, or your own tickers.

/api/v1/options-flow/top?type=p&min_premium=1000000&limit=20

GET/api/v1/options-flow/history/:symbol

Per-symbol end-of-day history of unusual flow (aggregated from contracts that passed the unusual filter) - daily call/put volume, premium, C/P ratios, average IV, net delta, and the consecutive-day streak. The series behind back-tests.

/api/v1/options-flow/history/:symbol/TSLA?date_from=2026-04-01&limit=90

GET/api/v1/options-flow/streaks

Multi-day unusual-flow streaks - symbols showing unusual options activity for N consecutive trading days, with the dominant side by C/P volume ratio. Persistent unusual flow is a stronger signal than a single print.

/api/v1/options-flow/streaks?min_streak=5&side=call&limit=50

GET/api/v1/options-flow/expiry

Expiry concentration - where the day's unusual premium sits along the DTE axis, in fixed buckets (0-7, 8-30, 31-90, 90+) with call/put splits. Heavy short-dated premium reads as event bets.

/api/v1/options-flow/expiry?symbols=NVDA,TSLA

GET/api/v1/options-flow/stats

Dataset coverage stats - available date ranges, contract counts, symbol counts, and sector coverage. Lets clients and agents discover what is queryable before they query it.

GET/api/v1/options-flow/sentiment

Per-symbol sentiment of the day's unusual flow - call/put volumes, total premium, net delta, C/P ratios, average IV per side, plus bullish/bearish classification with strengthScore 0-9 and the screener confirmations behind it.

/api/v1/options-flow/sentiment?signal_only=1&min_strength=6&sector=Information+Technology&limit=50

GET/api/v1/options-flow/sentiment/:symbol

Per-symbol unusual-flow sentiment time series. Defaults to the last 30 trading days; widen with date_from/date_to.

/api/v1/options-flow/sentiment/:symbol/NVDA?limit=60

GET/api/v1/options-flow/iv-rank

IV rank + IV percentile snapshot per symbol, computed against the symbol's rolling history. Symbols need >= 20 days of history to qualify. Side filter scopes ranking to calls or puts.

/api/v1/options-flow/iv-rank?side=put&min_rank=0.8&limit=50

GET/api/v1/options-flow/iv-rank/:symbol

Per-symbol IV rank time series. Each row carries that day's call/put IV with its rank and percentile against the full available history.

/api/v1/options-flow/iv-rank/:symbol/AMD?lookback_days=120

GET/api/v1/options-flow/oi-changes

Day-over-day open-interest change per symbol (total, calls, puts). min_prev_oi defaults to 1,000 to filter low-base noise. side=gainers|losers scopes to net positive or net negative OI deltas.

/api/v1/options-flow/oi-changes?side=gainers&min_change_pct=0.5&limit=50

GET/api/v1/options-flow/oi-changes/:symbol

Per-symbol OI change time series with day-over-day deltas at the total / call / put level.

/api/v1/options-flow/oi-changes/:symbol/NVDA?limit=60

GET/api/v1/options-flow/sectors

Sector-level rollup of the day's unusual flow - total premium, total volume, average net delta, and bullish/bearish symbol counts per GICS sector. Useful for spotting which corners of the market institutional flow is concentrated in.

/api/v1/options-flow/sectors?limit=11

GET/api/v1/options-flow/market

Market-wide breadth of unusual flow + regime. One row per trading day with the breadth score, aggregate call/put ratio, regime label (bullish/bearish/mixed), and bullish/bearish symbol counts.

/api/v1/options-flow/market?limit=30

GET/api/v1/health

Service health probe. Public, returns 200 when the database is reachable.

GET/api/v1/ping

Latency probe. Public, returns a tiny JSON with server time.

Query parameters

Both flow endpoints (/unusual and /:symbol) accept the same filters. Default scope is the latest scan day - everything else is opt-in.

Time scope

Param	Type	Behavior
(none)	default	Latest scan day available.
date	YYYY-MM-DD	A specific scan day.
date_from	YYYY-MM-DD	Inclusive lower bound. Combine with date_to for a range.
date_to	YYYY-MM-DD	Inclusive upper bound.
since	ISO 8601	Contracts whose intraday last_seen_at >= this timestamp. Useful for polling clients.

Symbol scope

Param	Type	Behavior
symbols	comma list	Restrict to one or more tickers, e.g. `?symbols=AAPL,NVDA,TSLA`. Ignored on /:symbol routes.

Contract filters

Param	Type	Behavior
type	c \| p \| all	Calls only, puts only, or both (default).
min_voloi	number	Vol/OI ratio floor. Default 1.5 unless raw=1.
min_premium	number ($)	Total premium = last_price * volume * 100. Default $25k unless raw=1.
min_iv	number (%)	Implied volatility floor.
max_dte	integer	Max days to expiration.
min_volume	integer	Raw contract volume floor.
min_oi	integer	Open interest floor. Default 100 unless raw=1.
raw	0 \| 1	If 1, skips the always-on base floor (Vol/OI>=1.5, OI>=100, premium>=$25k). Use only if you want the unfiltered tape.
limit	integer	Max rows. Default 300 (100 on /:symbol), max 1000 (500 on /:symbol).

Examples

# Latest scan, default filters
GET /api/v1/options-flow/unusual

# Calls only on NVDA + TSLA with Vol/OI >= 5 and $250k+ premium
GET /api/v1/options-flow/unusual?symbols=NVDA,TSLA&type=c&min_voloi=5&min_premium=250000

# Last 7 days of AAPL flow, ordered by significance
GET /api/v1/options-flow/AAPL?date_from=2026-06-01&date_to=2026-06-07

# Anything new in the last 10 minutes (polling)
GET /api/v1/options-flow/unusual?since=2026-06-08T14:30:00Z

# Short-dated put hedging, IV > 60%, DTE <= 14
GET /api/v1/options-flow/unusual?type=p&min_iv=60&max_dte=14

Error responses

All errors return JSON in the form { error, code, status }.

Code	Meaning
MISSING_API_KEY	No X-API-Key header. 401.
INVALID_API_KEY_FORMAT	Key does not match expected format. 401.
INVALID_API_KEY	Key not recognized. 401.
NO_ACTIVE_SUBSCRIPTION	Key valid but no paid tier attached. 403.
SUBSCRIPTION_INACTIVE	Subscription past_due or expired. 403.
RATE_LIMIT_MINUTE	Per-minute cap hit for your tier. 429.
RATE_LIMIT_DAY	Daily cap hit for your tier. 429.
AUTH_UNAVAILABLE	Auth backend temporarily down. 503.

Coverage and freshness

7,000+ US-listed common stocks and ADRs with active options.
Unusual flow scanned every 5 minutes through the trading session.
Data persisted for the current trading day; previous-day archives via the historical endpoint (Pro tier).
All times in ET (America/New_York).

Get a key

Generate your API key in seconds

Subscribe, then create a key from your settings. Keys are scoped per-account and revocable any time.

Go to settings →