This example shows how to use the Historical client to retrieve instrument definitions for all options on futures with a given underlying. This is useful for complex assets such as the options on E-mini S&P 500 Futures which have different symbols for their quarterly, monthly (serial), weekly, and daily options.

We'll use the definition schema, which contains instrument definitions and properties such as the security type and underlying of the instrument. We'll request the definitions for all symbols, and then filter the instruments using the security_type and underlying fields. We'll show the asset field, which refers to the parent symbol for that option, as well as strike price and expiration .

Info
See the Options on E-Mini S&P 500 Futures FAQ page for more information on the ES Options symbology.

Example

Python

      
    
import databento as db

# Set underlying instrument
symbol = "ESH5"

# Create a historical client
client = db.Historical(key="$YOUR_API_KEY")

# Get definition data
data = client.timeseries.get_range(
    dataset="GLBX.MDP3",
    schema="definition",
    symbols="ALL_SYMBOLS",
    start="2025-03-10",
)

# Convert to DataFrame
df = data.to_df()

# Filter for instruments with a security type of "OOF" (options-on-futures)
df = df[df["security_type"] == "OOF"]

# Select only options for the specified underlying
df = df[df["underlying"] == symbol]

# Sort by strike price and select specific columns
df = df.sort_values("strike_price")
df = df[["raw_symbol", "underlying", "asset", "instrument_class", "strike_price", "expiration"]]

print(f"{len(df):,d}", f"option(s) for {symbol}")
print(df)

Python

6,494 option(s) for ESH5

See also
Check out the 0DTE symbols example on how to filter these options based on expiration.

Python

      
    
                             raw_symbol underlying asset instrument_class  strike_price                expiration
ts_recv
2025-03-10 00:00:00+00:00    E2AH5 P100       ESH5   E2A                P         100.0 2025-03-10 20:00:00+00:00
2025-03-10 00:00:00+00:00    E3DH5 C100       ESH5   E3D                C         100.0 2025-03-20 20:00:00+00:00
2025-03-10 00:00:00+00:00    E3AH5 C100       ESH5   E3A                C         100.0 2025-03-17 20:00:00+00:00
2025-03-10 00:00:00+00:00    E3DH5 P100       ESH5   E3D                P         100.0 2025-03-20 20:00:00+00:00
2025-03-10 00:00:00+00:00    E2DH5 P100       ESH5   E2D                P         100.0 2025-03-13 20:00:00+00:00
...                                 ...        ...   ...              ...           ...                       ...
2025-03-10 00:00:00+00:00    ESH5 P8500       ESH5    ES                P        8500.0 2025-03-21 13:30:00+00:00
2025-03-10 00:00:00+00:00    ESH5 P8600       ESH5    ES                P        8600.0 2025-03-21 13:30:00+00:00
2025-03-10 00:00:00+00:00    ESH5 C8600       ESH5    ES                C        8600.0 2025-03-21 13:30:00+00:00
2025-03-10 00:00:00+00:00  E3DH5 C10100       ESH5   E3D                C       10100.0 2025-03-20 20:00:00+00:00
2025-03-10 00:00:00+00:00  E3DH5 P10100       ESH5   E3D                P       10100.0 2025-03-20 20:00:00+00:00

[6494 rows x 6 columns]