Expirations

Get a list of current or historical option expiration dates for an underlying symbol.

Making Requests

Use the expirations() method on the options resource to fetch expiration dates. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with expiration dates indexed by expirations (default).
INTERNAL	OptionsExpirations or OptionsExpirationsHumanReadable	Returns an OptionsExpirations object. When use_human_readable=True, returns an OptionsExpirationsHumanReadable object with capitalized field names.
JSON	dict	Returns the raw JSON response as a dictionary.
CSV	str	Writes CSV data to file and returns the filename string.

expirations

def expirations(
    symbol: str,
    *,
    strike: float = None,
    date: str | datetime.datetime = None,
    output_format: OutputFormat = OutputFormat.DATAFRAME,
    date_format: DateFormat = None,
    columns: list[str] = None,
    add_headers: bool = None,
    use_human_readable: bool = False,
    mode: Mode = None,
    filename: str | Path = None,
) -> OptionsExpirations | OptionsExpirationsHumanReadable | dict | str | MarketDataClientErrorResult

Fetches available expiration dates for a given symbol. The symbol parameter can be passed as the first positional argument or as a keyword argument. All other parameters must be keyword-only.

Parameters

• symbol (str)

  The underlying stock symbol for which to fetch expiration dates.

• strike (float, optional)

  Filter by strike price.

• date (str | datetime.datetime, optional)

  Historical date for the expiration dates.

• output_format (OutputFormat, optional)

  The format of the returned data. Defaults to OutputFormat.DATAFRAME. See Settings for details.

• date_format (DateFormat, optional)

  The date format to use in the response. Defaults to DateFormat.UNIX. See Settings for details.

• columns (optional)

  Specify which columns to include in the response. See Settings for details.

• add_headers (optional)

  Whether to include headers in the response. See Settings for details.

• use_human_readable (optional)

  Whether to use human-readable format for values. Only applies when output_format=OutputFormat.INTERNAL. See Settings for details.

• mode (Mode, optional)

  The data feed mode to use. See Settings for details.

• filename (str | Path, optional)

  File path for CSV output (only used with output_format=OutputFormat.CSV).

Returns

• OptionsExpirations | OptionsExpirationsHumanReadable | dict | str | MarketDataClientErrorResult

  The expiration dates in the requested format, or a MarketDataClientErrorResult if an error occurred.

Example (DataFrame)

from marketdata.client import MarketDataClient

client = MarketDataClient()

# Get options expirations as DataFrame (default)
# symbol can be passed positionally or as keyword
df = client.options.expirations("AAPL")
# or
df = client.options.expirations(symbol="AAPL")

print(df)

Example (Internal)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get options expirations as internal object
expirations = client.options.expirations("AAPL", output_format=OutputFormat.INTERNAL)

# Access expiration dates
print(f"Expirations: {expirations.expirations}")

Example (JSON)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get options expirations as JSON
expirations = client.options.expirations("AAPL", output_format=OutputFormat.JSON)

print(expirations)

Example (CSV)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get options expirations as CSV
csv_file = client.options.expirations(
    "AAPL",
    output_format=OutputFormat.CSV,
    filename=Path("expirations.csv")
)

print(f"CSV file saved to: {csv_file}")

Example (Human Readable)

from marketdata.client import MarketDataClient
from marketdata.input_types.base import OutputFormat

client = MarketDataClient()

# Get options expirations in human-readable format
expirations = client.options.expirations(
    "AAPL",
    output_format=OutputFormat.INTERNAL,
    use_human_readable=True
)

# Access expiration dates
print(f"Expirations: {expirations.Expirations}")
print(f"Date: {expirations.Date}")

OptionsExpirations

@dataclass
class OptionsExpirations:
    s: str
    expirations: list[datetime.datetime]
    updated: datetime.datetime

OptionsExpirations represents expiration dates for options, encapsulating a list of expiration dates and an update timestamp.

Properties

• s (str): Status indicator ("ok" for successful responses).
• expirations (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
• updated (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).

Notes

• The expirations list contains datetime.datetime objects automatically converted from Unix timestamps.
• The updated field is automatically converted to a datetime.datetime object from a Unix timestamp.

OptionsExpirationsHumanReadable

@dataclass
class OptionsExpirationsHumanReadable:
    Expirations: list[datetime.datetime]
    Date: datetime.datetime

OptionsExpirationsHumanReadable represents expiration dates in human-readable format with capitalized field names and formatted values.

Properties

• Expirations (list[datetime.datetime]): List of expiration dates (automatically converted from timestamps).
• Date (datetime.datetime): The time when the data was last updated (automatically converted from timestamp).

Notes

• The Expirations list contains datetime.datetime objects automatically converted from Unix timestamps.
• The Date field is automatically converted to a datetime.datetime object from a Unix timestamp.
• Field names use capitalized format (e.g., Expirations instead of expirations, Date instead of updated).