In this example we will use the Historical client to retrieve a large number of instrument definitions using parent symbology. When requesting data with a parent symbol (ES.FUT), all contracts that trade under the parent name will be returned. This includes outright futures (ESM5), as well as calendar spreads (ESM5-ESU5).

See also
If you are only interested in the front month contract for a futures product, see our continuous symbology example.

We'll use the definition schema, which contains instrument definitions and properties such as expiration, raw_symbol, and instrument_class. instrument_class will indicate the type of instrument, such as future or future spread. A full list of variants can be found in the instrument class documentation.

Example

PythonC++Rust

      
    
import databento as db

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

# Request definition data
data = client.timeseries.get_range(
    dataset="GLBX.MDP3",
    start="2025-05-19",
    symbols="ES.FUT",
    stype_in="parent",
    schema="definition",
)

# Convert to DataFrame
df = data.to_df()

# Filter out spreads and sort by expiration
df = df[df["instrument_class"] == db.InstrumentClass.FUTURE]
df = df.set_index("expiration").sort_index()

print(df[["instrument_id", "raw_symbol"]])

Result

PythonC++Rust

      
    
                           instrument_id raw_symbol
expiration
2025-06-20 13:30:00+00:00           4916       ESM5
2025-09-19 13:30:00+00:00          14160       ESU5
2025-12-19 14:30:00+00:00         294973       ESZ5
2026-03-20 13:30:00+00:00       42140878       ESH6
2026-06-18 13:30:00+00:00       42140864       ESM6
...
2029-06-15 13:30:00+00:00       42005050       ESM9
2029-09-21 13:30:00+00:00       42000977       ESU9
2029-12-21 14:30:00+00:00       42004134       ESZ9
2030-03-15 13:30:00+00:00       42000746       ESH0
2030-06-21 13:30:00+00:00       42004092       ESM0