How can I download option chain historical data with API?

Question

Accepted Answer

The TWS API and Web API provide functionality to request the details of an option chain.

Prerequisites:

An active, funded IBKR account with a live market data subscription for the relevant exchange (required to access historical options data).
TWS (Trader Workstation) or IB Gateway installed and running with API connections enabled.
Python 3.12 or higher.
The ibapi library downloaded from https://download2.interactivebrokers.com/installers/tws-api/index.html
- Install the TWS API from https://www.interactivebrokers.com/docs/tws-api/doc/install-the-tws-api-on-windows or https://www.interactivebrokers.com/docs/tws-api/install-the-tws-api-on-mac-os-linux

Step 1: Understand the Two-Phase Approach

The IBKR API does NOT allow you to download an entire option chain's historical data in a single request. You must:

First, retrieve the option chain parameters (expirations and strikes) using `reqSecDefOptParams()`.
Then, request historical data for each individual option contract one at a time using `reqHistoricalData()`.

Step 2: Retrieve Option Chain Parameters

Use `reqSecDefOptParams()` to get all available expiration dates and strike prices for AES. This returns the full set of parameters for the option chain but does not specify which strikes are valid for each expiration individually.
If needed, use `reqContractDetails()` to validate which strikes are available for a specific expiration date (note: this approach can be slow for large chains like SPY, but is manageable for smaller underlyings like AES).

Step 3: Request Historical Data Per Contract

For each option contract (combination of expiration + strike + right [CALL/PUT]), call `reqHistoricalData()` with the appropriate parameters:

`whatToShow`: Use `'TRADES'` for price data, or `'OPTION_IMPLIED_VOLATILITY'` for IV data.
`barSizeSetting`: e.g., `'1 hour'`, `'1 day'`
`durationStr`: e.g., `'2 D'`, `'1 M'` (note: a space IS required between the number and the unit)

Step 4: Capture and Store Data

Since TWS API callbacks return `NoneType` objects by default, you must store incoming data in a Python list or dictionary within your `EWrapper` callback methods (e.g., `historicalData()`). Once collected, save the conids to a local file.

Key API Functions:

`reqSecDefOptParams()` — Retrieves option chain parameters (expirations, strikes, exchanges)
`reqContractDetails()` — Validates specific contracts
`reqHistoricalData()` — Retrieves historical OHLCV or IV data for one contract at a time
`reqHistoricalTicks()` — Retrieves tick-by-tick historical data

Please Note

Historical data can only be requested one option contract at a time — bulk chain downloads are not supported.
You must have an active live market data subscription to access historical options data.
API request pacing rules apply; add delays between requests to avoid throttling.

If an expiration date does not exist for AES, `reqContractDetails()` will return no results for that date — handle this gracefully in your code.

Additional Information