Earnings (Python SDK)

• Last updated Sep 3, 2026
• View as Markdown

Retrieve earnings data for any supported stock symbol.

Making Requests

Use the earnings() method on the stocks resource to fetch earnings data. The method supports multiple output formats:

Output Format	Return Type	Description
DATAFRAME	pandas.DataFrame or polars.DataFrame	Returns a DataFrame with earnings data indexed by symbol (default).
INTERNAL	StockEarnings or StockEarningsHumanReadable	Returns a StockEarnings object. When use_human_readable=True, returns a StockEarningsHumanReadable 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.

earnings

def earnings(
    symbol: str,
    *,
    report: str = None,
    date: str | datetime.datetime = None,
    from_date: str | datetime.datetime = None,
    to_date: str | datetime.datetime = None,
    countback: int = 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,
) -> StockEarnings | StockEarningsHumanReadable | dict | str | MarketDataClientErrorResult

Fetches earnings data for a stock 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 stock symbol for which to fetch earnings data.

• report (str, optional)

  Filter by report type (e.g., "annual", "quarterly").

• date (str | datetime.datetime, optional)

  Specific date for the earnings data.

• from_date (str | datetime.datetime, optional)

  Start date for the date range.

• to_date (str | datetime.datetime, optional)

  End date for the date range.

• countback (int, optional)

  Number of earnings reports to return, counting backwards from the to_date.

• 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 mode to use. See Settings for details.

• filename (str | Path, optional)

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

Returns

• StockEarnings | StockEarningsHumanReadable | dict | str | MarketDataClientErrorResult

  The earnings data in the requested format, or a MarketDataClientErrorResult if an error occurred.

Example (DataFrame)

from marketdata import MarketDataClient

client = MarketDataClient()

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

print(df)

Example (Internal)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock earnings as internal object
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.INTERNAL)

# Access earnings properties
print(f"Symbol: {earnings.symbol}")
print(f"Fiscal Year: {earnings.fiscalYear}")
print(f"Fiscal Quarter: {earnings.fiscalQuarter}")
print(f"Reported EPS: {earnings.reportedEPS}")
print(f"Estimated EPS: {earnings.estimatedEPS}")

Example (JSON)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

# Get stock earnings as JSON
earnings = client.stocks.earnings("AAPL", output_format=OutputFormat.JSON)

print(earnings)

Example (CSV)

from marketdata import MarketDataClient, OutputFormat
from pathlib import Path

client = MarketDataClient()

# Get stock earnings as CSV
csv_file = client.stocks.earnings(
    "AAPL",
    output_format=OutputFormat.CSV,
    filename=Path("earnings.csv")
)

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

Example (Human Readable)

from marketdata import MarketDataClient, OutputFormat

client = MarketDataClient()

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

# Access earnings properties
print(f"Symbol: {earnings.Symbol}")
print(f"Fiscal Year: {earnings.Fiscal_Year}")
print(f"Fiscal Quarter: {earnings.Fiscal_Quarter}")
print(f"Reported EPS: {earnings.Reported_EPS}")
print(f"Estimated EPS: {earnings.Estimated_EPS}")
print(f"Surprise EPS: {earnings.Surprise_EPS}")

StockEarnings

@dataclass
class StockEarnings:
    s: str
    symbol: list[str]
    fiscalYear: list[int]
    fiscalQuarter: list[int]
    date: list[datetime.datetime]
    reportDate: list[datetime.datetime]
    reportTime: list[str]
    currency: list[str]
    reportedEPS: list[float]
    estimatedEPS: list[float]
    surpriseEPS: list[float]
    surpriseEPSpct: list[float]
    updated: list[datetime.datetime]

StockEarnings represents earnings data for a stock, encapsulating fiscal year, quarter, and EPS information. All lists have the same length, allowing you to access earnings data by index.

Properties

• s (str): Status indicator ("ok" for successful responses).
• symbol (list[str]): List of stock symbols.
• fiscalYear (list[int]): List of fiscal years.
• fiscalQuarter (list[int]): List of fiscal quarters.
• date (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
• reportDate (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
• reportTime (list[str]): List of report times.
• currency (list[str]): List of currencies.
• reportedEPS (list[float]): List of reported earnings per share.
• estimatedEPS (list[float]): List of estimated earnings per share.
• surpriseEPS (list[float]): List of surprise earnings per share (difference between reported and estimated).
• surpriseEPSpct (list[float]): List of surprise EPS percentages.
• updated (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).

StockEarningsHumanReadable

@dataclass
class StockEarningsHumanReadable:
    Symbol: list[str]
    Fiscal_Year: list[int]
    Fiscal_Quarter: list[int]
    Date: list[datetime.datetime]
    Report_Date: list[datetime.datetime]
    Report_Time: list[str]
    Currency: list[str]
    Reported_EPS: list[float]
    Estimated_EPS: list[float]
    Surprise_EPS: list[float]
    Surprise_EPS_Percent: list[float]
    Updated: list[datetime.datetime]

StockEarningsHumanReadable represents earnings data in human-readable format with capitalized field names and formatted values. All lists have the same length, allowing you to access earnings data by index.

Properties

• Symbol (list[str]): List of stock symbols.
• Fiscal_Year (list[int]): List of fiscal years.
• Fiscal_Quarter (list[int]): List of fiscal quarters.
• Date (list[datetime.datetime]): List of earnings dates (automatically converted from timestamps).
• Report_Date (list[datetime.datetime]): List of report dates (automatically converted from timestamps).
• Report_Time (list[str]): List of report times.
• Currency (list[str]): List of currencies.
• Reported_EPS (list[float]): List of reported earnings per share.
• Estimated_EPS (list[float]): List of estimated earnings per share.
• Surprise_EPS (list[float]): List of surprise earnings per share (difference between reported and estimated).
• Surprise_EPS_Percent (list[float]): List of surprise EPS percentages.
• Updated (list[datetime.datetime]): List of last update timestamps (automatically converted from timestamps).

Notes

• Field names use capitalized format with underscores (e.g., Fiscal_Year instead of fiscalYear, Reported_EPS instead of reportedEPS).