Strategy Guides

Option Screener Guide

The WSO screener (POST /v1/contracts/screen) executes scans across US options chains using server-side filtering across Greeks, volatility metrics, return on collateral, and earnings calendars.

Start with 2–3 Filters

Start your screener query with 2–3 broad filters (e.g. type, dteMin/dteMax, and deltaMin/deltaMax) before layering on liquidity constraints or spread ceilings.

Request Formats: Direct Aliases & Filter Array

The screener accepts either convenient top-level alias fields (like deltaMin, dteMin, bidAskSpreadPctMax, or symbols) or an explicit filters array of filter rules.

Filter Operators (from OpenAPI Spec)

Generated directly from the OpenAPI specification FilterItem.operation enum:

Category	Operations	Description
Comparison	gtgteltlteeq>>=<<====	Numerical and date threshold comparisons
Pattern Matching	like	Substring matching on text columns (e.g. consensus, symbol)
Set Membership	inexclude	Array or comma-separated list inclusion / exclusion
Specialized Filters	excludeEarningscleanupLiquiditylastTradeTodaylastTradeRecentstrikeFilter	Domain-specific filters for earnings dates, liquidity criteria, and strike distances
Ordering	sort	Multi-factor ordering using value "asc" or "desc"

Supported Filter & Sort Fields (from OpenAPI Spec)

98 accepted fields

Data Kind	Supported Fields
Contract & Option Spec	call, cushion, daysToExpiration, dte, expiration, expirationDays, expiration_days, moneyness, put, strike, strikeFilter, type
Pricing & Spreads	annualizedReturn, askPrice, bidAskSpread, bidAskSpreadAbs, bidAskSpreadDollar, bidAskSpreadPct, bidAskSpreadPercent, bidPrice, lastPrice, markOneDayAgo, premium, premiumChange1dPct, spread, spreadAbs, spreadPct, stockPrice, thirtyDayAveragePremium, yieldPercent
Greeks & Volatility	delta, gamma, highestStockIV, impliedVolatility, iv, ivr, lowestStockIV, stockIV, theta, thirtyDayAverageIV, vega
Volume & Liquidity	liquidity, openInterest, openInterestHistorySamples30d, openInterestStdDevDiff, openInterestStdDevDiff30d, openInterestZScore, openInterestZScore30d, premiumIncreasing, premiumIncreasing30d, thirtyDayAverageVolume, volume, volumeHistorySamples30d, volumeStdDevDiff, volumeStdDevDiff30d, volumeZScore, volumeZScore30d
Underlying & Fundamentals	consensus, fiftyDayAverage, fiftyTwoWeekHigh, fiftyTwoWeekLow, industry, lastTradeDate, lastUpdatedDate, marketCap, peRatio, probability, rating, rsi, sector, stockType, symbol, symbolType, symbols, twoHundredDayAverage
Earnings & Calendars	dividendFrequency, dividendIsEstimated, dividendYield, dividendamount, dividenddate, dividenddays, dividendpaymentdate, earnings, earningsDate, exdividenddate, nextDividendAmount, nextDividendDate, nextDividendDays, nextDividendIsEstimated, nextDividendPaymentDate
Scoring & Financial Health	contractScore, debtToEquityScore, discountedCashFlowScore, overallScore, priceToBookScore, priceToEarningsScore, returnOnAssetsScore, returnOnEquityScore

Sorting Grammar & Explicit Ordering

Screener queries specify ordering using explicit sort filter predicates: {"field": "<field>", "operation": "sort", "value": "asc" | "desc"}.

Accepted directions for value are "asc", "desc", "ascending", and "descending" (empty or omitted defaults to "asc"). Supplying an explicit sort predicate (for example {"field": "contractScore", "operation": "sort", "value": "desc"}) is recommended. When no sort filter is supplied, contracts default to option_key ASC (or expiration ASC, strike ASC, option_key ASC when a single symbol is pinned).

Earnings Calendar Exclusion Semantics

The screener provides two distinct modes for excluding earnings risk via excludeEarnings:

Contract Mode (default): {"field": "earnings", "operation": "excludeEarnings"} (or omitting value) drops contracts whose expiration date falls within ±7 days of the company's earnings date. Expirations outside that ±7 day window remain eligible.
Symbol Mode: {"field": "earnings", "operation": "excludeEarnings", "value": "symbol"} (or "ticker") drops all contracts for any underlying equity scheduled to report earnings within the next 7 calendar days (earningsDate ≤ CURRENT_DATE + 7d).

Note: Neither mode drops contracts solely because their expiration spans an earnings event. Exclusion is strictly evaluated against the ±7 day expiration window or the 7-day upcoming announcement window.

Worked Examples

Example 1

Cash-Secured Put Candidates (30–45 DTE, -0.30 to -0.20 Delta)

Standard 30–45 DTE cash-secured put selling setup seeking 20–30 delta out-of-the-money puts with minimum open interest and 1.5%+ raw return on collateral:

json

{
  "type": "put",
  "dteMin": 30,
  "dteMax": 45,
  "deltaMin": -0.3,
  "deltaMax": -0.2,
  "openInterestMin": 500,
  "yieldPercentMin": 1.5,
  "perPage": 10
}

Example 2

Covered-Call Candidates across Watchlist

Scans specific underlying holdings for call selling opportunities between 21 and 45 DTE with delta between 0.25 and 0.35 and tight bid-ask spreads (bidAskSpreadPctMax is percent: 8 means 8%):

json

{
  "type": "call",
  "symbols": [
    "AAPL",
    "MSFT",
    "NVDA"
  ],
  "dteMin": 21,
  "dteMax": 45,
  "deltaMin": 0.25,
  "deltaMax": 0.35,
  "bidAskSpreadPctMax": 8,
  "perPage": 10
}

Example 3

High IV Rank Excluding Earnings Window

Filters for options with high Implied Volatility Rank (IVR >= 50) while excluding contracts whose expiration falls within ±7 days of an earnings date (or use {"field": "earnings", "operation": "excludeEarnings", "value": "symbol"} to exclude underlyings reporting within the next 7 days):

json

{
  "filters": [
    {
      "field": "ivr",
      "operation": "gte",
      "value": 50
    },
    {
      "field": "type",
      "operation": "eq",
      "value": "put"
    },
    {
      "field": "dte",
      "operation": "lte",
      "value": 45
    },
    {
      "field": "earnings",
      "operation": "excludeEarnings"
    }
  ],
  "perPage": 10
}

Example 4

Ranked by Contract Score (Explicit Sort)

Demonstrates explicit multi-factor sorting using {"field": "<field>", "operation": "sort", "value": "asc"|"desc"}. Supplying an explicit sort predicate is recommended over relying on default order:

json

{
  "type": "put",
  "dteMin": 30,
  "dteMax": 45,
  "deltaMin": -0.3,
  "deltaMax": -0.2,
  "filters": [
    {
      "field": "contractScore",
      "operation": "sort",
      "value": "desc"
    }
  ],
  "perPage": 10
}

Sample Screener Response

Returns array of matching contracts with derived yield metrics and Greeks:

json

{
  "count": 1000,
  "countCapped": true,
  "hasMore": true,
  "results": [
    {
      "symbol": "A",
      "type": "call",
      "expiration": "2026-10-16T00:00:00Z",
      "strike": 140,
      "yieldPercent": 16.86,
      "bidPrice": 23.6,
      "volume": 3,
      "openInterest": 44,
      "delta": 0.97663,
      "annualizedReturn": 876.8803,
      "lastUpdatedDate": "2026-10-09T19:33:52.362Z",
      "optionKey": "A261016C00140000",
      "probability": 0.02406497,
      "yesterdayMark": 29.3,
      "thirtyDayAverageVolume": 2,
      "thirtyDayAverageIV": 0.44,
      "thirtyDayAveragePremium": 2130,
      "premiumChange1dPct": null,
      "volumeZScore30d": 0.19,
      "openInterestZScore30d": -2.98,
      "volumeStdDev30d": 3.86,
      "openInterestStdDev30d": 22.84,
      "volumeHistorySamples30d": 22,
      "openInterestHistorySamples30d": 22,
      "contractScore": 0.3483,
      "premium": 2360,
      "lastPrice": 16.65,
      "lastTradeDate": "2026-09-18T19:14:26.111Z",
      "askPrice": 26.6,
      "stockPrice": 171.031311035156,
      "impliedVolatility": 75.2,
      "vega": 0.01306,
      "gamma": 0.00308,
      "theta": -0.08217,
      "earningsDate": "2026-11-23T00:00:00Z",
      "marketCap": 47302000000,
      "industry": "Diagnostics & Research",
      "sector": "Healthcare",
      "peRatio": 33.0927,
      "rating": "B+",
      "consensus": "Buy",
      "overallScore": 3,
      "discountedCashFlowScore": 3,
      "returnOnEquityScore": 5,
      "returnOnAssetsScore": 5,
      "debtToEquityScore": 1,
      "priceToEarningsScore": 2,
      "priceToBookScore": 2,
      "rsi": 59.197136081869125,
      "stockIV": 32.9,
      "ivr": 59.0747,
      "lowestStockIV": 16.3,
      "highestStockIV": 44.4,
      "lowestStockIVDate": "2026-07-29",
      "highestStockIVDate": "2026-05-27",
      "fiftyTwoWeekLow": 108.35,
      "fiftyTwoWeekHigh": 177.05,
      "fiftyDayAverage": 152.5316,
      "twoHundredDayAverage": 132.8269,
      "dividendYield": 0.602374,
      "nextDividendDate": "2027-01-06",
      "nextDividendIsEstimated": true,
      "nextDividendPaymentDate": null,
      "nextDividendAmount": 0.255,
      "dividendFrequency": "Quarterly",
      "logoUrl": "https://images.financialmodelingprep.com/symbol/A.png"
    }
  ]
}

← Errors & Troubleshooting API Reference →