# Yahoo Finance Options Chain Scraper (`s-r/yahoo-options-chain`) Actor

Collect Yahoo Finance option contracts with expiration dates, strikes, bid/ask, volume, open interest and implied volatility. Filter calls and puts and keep the underlying price with each row.

- **URL**: https://apify.com/s-r/yahoo-options-chain.md
- **Developed by:** [SR](https://apify.com/s-r) (community)
- **Categories:** Business, Developer tools
- **Stats:** 5 total users, 5 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 yahoo option contracts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Yahoo Finance Options Chain Scraper

Get the Yahoo Finance options chain as structured contract rows for US-listed stocks, ETFs and indices. Choose tickers, expiration dates, calls or puts, and strike or moneyness filters. Each delivered row includes the contract identity, prices and the underlying quote, ready to export or join with your own analysis.

### What the Yahoo Finance options chain contains

This Actor collects the option contracts that Yahoo Finance reports for each requested symbol. It returns one row for each contract, rather than a separate summary row for each company or expiration. Calls and puts remain separate records, identified by `contract_symbol`. The underlying symbol, price, quote time and market state travel with every contract so that a saved dataset can be interpreted later.

Use the dataset to compare bid and ask spreads, track open interest, inspect reported implied volatility or maintain an option watchlist. Selecting explicit expirations makes it easier to join successive runs by contract symbol. Selecting all expirations lets you build a broader view of the reported chain, subject to the total result limit you choose.

Yahoo options data is delayed by 15 minutes. Outside market hours, the underlying regular-market price represents the closing market quote. The retrieval timestamp does not imply that a contract traded at that moment: `last_trade_at` records its actual last reported trade. This distinction matters for thinly traded contracts and historical comparisons.

### Input

Provide `tickers` as a list of Yahoo Finance symbols, for example the captured request below. Comma-separated ticker text is also accepted. Symbols are trimmed, converted to uppercase and deduplicated. Use the Yahoo symbol form for indices and share classes, such as `^SPX` and `BRK-B`. At most 100 distinct symbols are accepted in one run.

For share classes, use `BRK-B` instead of `BRK.B`. A dotted symbol with no listed expirations receives a reminder about this convention. Exchange suffixes such as `.AS` remain part of their Yahoo symbol; the Actor does not automatically replace dots or retry a different symbol.

The default `expirations` selection is `nearest`, with both calls and puts. Choose `next_n` and set `max_expirations` to select the first N listed dates, or choose `all` for every listed expiration. With `dates`, provide `expiration_dates` as valid `YYYY-MM-DD` strings. A date that is valid but not listed for a ticker produces a warning rather than an invented contract.

`contract_type` accepts `both`, `call` or `put`. The inclusive `min_strike` and `max_strike` fields select an absolute strike range. `moneyness` accepts `all`, `in_the_money` or `out_of_the_money` and follows Yahoo's reported flag. `strike_window_percent` selects a symmetric percentage window around the underlying market price. If that price is unavailable, the affected ticker cannot satisfy this window and receives a warning.

Optional `min_days_to_expiration` and `max_days_to_expiration` bound the number of calendar days until expiration. Both use the initial run date in UTC, including zero days for today's expiration. With `nearest` or `next_n`, the first one or N listed expirations are selected within this inclusive days window. `max_results` defaults to 1,000 and is a total limit across all tickers and expirations, up to 100,000 contracts. All enabled filters apply together.

```json
{
  "tickers": [
    "AAPL"
  ]
}
```

This input was used for the real source capture in the output example. Its October 2026 contract values are historical evidence of the output shape; a new run returns the currently reported chain.

### Output

The default dataset contains contract rows. A real captured AAPL contract, projected into the Actor's field names, is shown below. The complete corresponding source response and example are preserved with this product.

```json
{
  "source": "yahoo-options-chain",
  "fetched_at": "2026-10-12T00:13:26.393Z",
  "contract_symbol": "AAPL261012C00250000",
  "underlying_symbol": "AAPL",
  "option_type": "call",
  "strike": 250,
  "expiration_date": "2026-10-12",
  "expiration_timestamp": 1791763200,
  "days_to_expiration": 0,
  "last_price": 86.8,
  "bid": 85.5,
  "ask": 88.15,
  "volume": 10,
  "open_interest": 13,
  "implied_volatility": 1.818360283203125,
  "in_the_money": true,
  "currency": "USD",
  "underlying_price": 336.64,
  "mid": 86.825,
  "spread": 2.6500000000000057,
  "change": -1.8099976,
  "percent_change": -2.042656,
  "last_trade_at": "2026-10-09T19:44:27.000Z",
  "contract_size": "REGULAR",
  "underlying_price_at": "2026-10-09T20:00:00.000Z",
  "underlying_market_state": "CLOSED",
  "underlying_name": "Apple Inc."
}
```

`expiration_date` is the readable UTC date and `expiration_timestamp` is the source epoch in seconds. `implied_volatility` is a fraction: a value of 0.25 means 25 percent. `percent_change` uses Yahoo's percentage value. `mid` is computed only when both bid and ask are positive; `spread` is ask minus bid when both values exist.

Missing source values remain `null`. A missing trading volume, bid or open interest is not silently changed into zero. A source zero stays zero. This lets you distinguish unavailable information from a reported lack of activity. The Actor reports source values and these simple arithmetic fields; Greeks are not included.

The `OUTPUT` record in the default key-value store contains run counts and delivery status. Diagnostic warnings describe unknown tickers, unsupported instruments, unlisted dates and requests that could not finish. Warnings are separate from dataset records and do not count as option contracts. A ticker without matches contributes no contract rows. When another ticker has matches, those real rows are retained.

### Use cases

- **Volatility analysis.** Collect `implied_volatility` for several expirations of one ticker and compare the term structure across strikes, or follow one expiration over repeated runs.
- **Options screening.** Filter by call or put, strike window and days to expiration, then rank the delivered rows by `volume` or `open_interest` in your own tool.
- **Trading tools and dashboards.** Feed a spreadsheet, database or notebook with one row per contract, each carrying the underlying price so no second lookup is needed.
- **Liquidity checks.** Use `bid`, `ask`, `mid` and `spread` to find contracts that are cheap to enter and exit, and to spot zero-bid contracts.
- **Research datasets.** Store dated captures with `fetched_at` and join them on `contract_symbol` to study how open interest and quotes evolve.

### How this compares with other options on Apify

Some Yahoo options Actors add calculated Greeks, an unusual-activity mode or many sort orders. This Actor takes a narrower approach: it returns the contract values Yahoo reports, plus a few plain arithmetic fields (`mid`, `spread`, `days_to_expiration`), with filters for expiration, call or put, strike range, moneyness and days to expiration. Missing values stay `null` instead of being filled in, and you pay only for contracts that land in the dataset. If you need Greeks or a ranked list of unusual trades, calculate them from these rows or choose a tool built for that.

### Pricing and delivery limits

Billing is per delivered option contract, under the `option_contract` event. Only rows actually delivered to the default dataset count toward this event. An empty result contributes no billable contract. The current event price is displayed in this Actor's pricing tab; consult it when estimating the cost of a scheduled run.

Users without a paid Apify plan receive at most ten contract rows per run. This is a delivery cap, and delivered rows still follow the displayed event price. Paid-plan users can request the full selected volume up to `max_results`. The Actor follows continuation pages automatically, combines contract rows by their identity, and charges for the final delivered dataset once.

### FAQ

#### Which instruments have options?

The supported source coverage is US-listed stocks, ETFs and indices with reported Yahoo options. A valid ticker may have no option chain. The research capture for `ASML.AS` and `BTC-USD` had no options, while AAPL and `^SPX` had contract rows. Coverage and listed dates can change.

#### Does all mean an unlimited number of contracts?

It selects all listed expiration dates, while `max_results` still limits the total delivered contracts. Raise that field if the default 1,000 rows is too small. The run may report partial delivery when a source request or the available run time prevents completion; review OUTPUT and warnings before treating it as a complete chain.

#### Can I use these values as live execution prices?

The source data is delayed by 15 minutes, and individual contracts can have older last trades or zero bids. Read the source quote time, last trade time and market state alongside each price. Retrieval time describes when the record was fetched, not when every reported value changed.

#### How do repeated runs join together?

Use `contract_symbol` for the same option contract and `underlying_symbol` to group its company or index. Preserve `fetched_at` when comparing captures over time. Prices can change between continuation pages, so one run is a sequence of retrieved source responses rather than a guaranteed atomic market snapshot.

# Actor input Schema

## `tickers` (type: `array`):

Yahoo Finance symbols, as an array or comma-separated text. US-listed stocks, ETFs and indices are supported.

## `expirations` (type: `string`):

Select the nearest expiration, the next N, all expirations, or explicit dates.

## `max_expirations` (type: `integer`):

Number of nearest expirations when expirations is next_n.

## `expiration_dates` (type: `array`):

Explicit UTC expiration dates when expirations is dates. Unlisted dates produce warnings.

## `min_days_to_expiration` (type: `integer`):

Minimum days until expiration, inclusive, using the initial run date in UTC.

## `max_days_to_expiration` (type: `integer`):

Maximum days until expiration, inclusive, using the initial run date in UTC.

## `contract_type` (type: `string`):

Return both calls and puts, or only the selected type.

## `min_strike` (type: `number`):

Minimum strike price, inclusive; also sent to Yahoo to reduce response size.

## `max_strike` (type: `number`):

Maximum strike price, inclusive; also sent to Yahoo to reduce response size.

## `moneyness` (type: `string`):

Filter using the source in-the-money flag.

## `strike_window_percent` (type: `number`):

Keep strikes within this percentage above or below the underlying market price. Requires an available underlying price.

## `max_results` (type: `integer`):

Total maximum number of delivered contracts across all tickers and cursor pages.

## `cursor` (type: `string`):

Opaque continuation token returned as next_cursor. Keep all other input fields identical. Valid for at most two UTC days.

## Actor input object example

```json
{
  "tickers": [
    "AAPL",
    "SPY"
  ],
  "expirations": "nearest",
  "max_expirations": 1,
  "expiration_dates": [],
  "contract_type": "both",
  "moneyness": "all",
  "max_results": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

One row per delivered Yahoo Finance option contract.

## `output` (type: `string`):

OUTPUT record with the run's counts and status flags.

## `errors` (type: `string`):

Failures with a code and a redacted message. Absent when the run had none.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "tickers": [
        "AAPL",
        "SPY"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("s-r/yahoo-options-chain").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "tickers": [
        "AAPL",
        "SPY",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("s-r/yahoo-options-chain").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "tickers": [
    "AAPL",
    "SPY"
  ]
}' |
apify call s-r/yahoo-options-chain --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,s-r/yahoo-options-chain"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/aqr8R6PvjgDhiMmDR/builds/uLEcDIUX5HF5VMApv/openapi.json