Skip to main content
GET
/
earnings
Get earnings snapshot
curl --request GET \
  --url https://api.financialdatasets.ai/earnings \
  --header 'X-API-KEY: <api-key>'
{
  "earnings": [
    {
      "ticker": "<string>",
      "report_period": "2023-12-25",
      "source_type": "8-K",
      "filing_date": "2023-12-25",
      "filing_url": "<string>",
      "accession_number": "<string>",
      "fiscal_period": "<string>",
      "currency": "<string>",
      "filing_datetime": "2023-11-07T05:31:56Z",
      "filing_window": "PRE_MARKET",
      "signals": [
        {
          "type": "EPS_BEAT",
          "headline": "<string>",
          "metric": "<string>",
          "period": "<string>",
          "details": {}
        }
      ],
      "quarterly": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "estimated_revenue": 123,
        "revenue_surprise": "BEAT",
        "revenue_surprise_pct": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 123,
        "estimated_earnings_per_share": 123,
        "eps_surprise": "BEAT",
        "eps_surprise_pct": 123,
        "gross_profit": 123,
        "gross_profit_chg": 123,
        "gross_profit_yoy_chg": 123,
        "gross_margin": 123,
        "gross_margin_chg_bps": 123,
        "gross_margin_chg_pct": 123,
        "gross_margin_yoy_chg_bps": 123,
        "gross_margin_yoy_chg_pct": 123,
        "operating_income": 123,
        "operating_income_chg": 123,
        "operating_income_yoy_chg": 123,
        "operating_margin": 123,
        "operating_margin_chg_bps": 123,
        "operating_margin_chg_pct": 123,
        "operating_margin_yoy_chg_bps": 123,
        "operating_margin_yoy_chg_pct": 123,
        "net_income": 123,
        "net_income_chg": 123,
        "net_income_yoy_chg": 123,
        "net_margin": 123,
        "net_margin_chg_bps": 123,
        "net_margin_chg_pct": 123,
        "net_margin_yoy_chg_bps": 123,
        "net_margin_yoy_chg_pct": 123,
        "weighted_average_shares": 123,
        "weighted_average_shares_diluted": 123,
        "cash_and_equivalents": 123,
        "change_in_cash_and_equivalents": 123,
        "total_debt": 123,
        "total_assets": 123,
        "total_liabilities": 123,
        "shareholders_equity": 123,
        "net_cash_flow_from_operations": 123,
        "net_cash_flow_from_operations_chg": 123,
        "net_cash_flow_from_operations_yoy_chg": 123,
        "net_cash_flow_from_investing": 123,
        "net_cash_flow_from_investing_chg": 123,
        "net_cash_flow_from_investing_yoy_chg": 123,
        "net_cash_flow_from_financing": 123,
        "net_cash_flow_from_financing_chg": 123,
        "net_cash_flow_from_financing_yoy_chg": 123,
        "capital_expenditure": 123,
        "capital_expenditure_chg": 123,
        "capital_expenditure_yoy_chg": 123,
        "free_cash_flow": 123,
        "free_cash_flow_chg": 123,
        "free_cash_flow_yoy_chg": 123
      },
      "annual": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "estimated_revenue": 123,
        "revenue_surprise": "BEAT",
        "revenue_surprise_pct": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 123,
        "estimated_earnings_per_share": 123,
        "eps_surprise": "BEAT",
        "eps_surprise_pct": 123,
        "gross_profit": 123,
        "gross_profit_chg": 123,
        "gross_profit_yoy_chg": 123,
        "gross_margin": 123,
        "gross_margin_chg_bps": 123,
        "gross_margin_chg_pct": 123,
        "gross_margin_yoy_chg_bps": 123,
        "gross_margin_yoy_chg_pct": 123,
        "operating_income": 123,
        "operating_income_chg": 123,
        "operating_income_yoy_chg": 123,
        "operating_margin": 123,
        "operating_margin_chg_bps": 123,
        "operating_margin_chg_pct": 123,
        "operating_margin_yoy_chg_bps": 123,
        "operating_margin_yoy_chg_pct": 123,
        "net_income": 123,
        "net_income_chg": 123,
        "net_income_yoy_chg": 123,
        "net_margin": 123,
        "net_margin_chg_bps": 123,
        "net_margin_chg_pct": 123,
        "net_margin_yoy_chg_bps": 123,
        "net_margin_yoy_chg_pct": 123,
        "weighted_average_shares": 123,
        "weighted_average_shares_diluted": 123,
        "cash_and_equivalents": 123,
        "change_in_cash_and_equivalents": 123,
        "total_debt": 123,
        "total_assets": 123,
        "total_liabilities": 123,
        "shareholders_equity": 123,
        "net_cash_flow_from_operations": 123,
        "net_cash_flow_from_operations_chg": 123,
        "net_cash_flow_from_operations_yoy_chg": 123,
        "net_cash_flow_from_investing": 123,
        "net_cash_flow_from_investing_chg": 123,
        "net_cash_flow_from_investing_yoy_chg": 123,
        "net_cash_flow_from_financing": 123,
        "net_cash_flow_from_financing_chg": 123,
        "net_cash_flow_from_financing_yoy_chg": 123,
        "capital_expenditure": 123,
        "capital_expenditure_chg": 123,
        "capital_expenditure_yoy_chg": 123,
        "free_cash_flow": 123,
        "free_cash_flow_chg": 123,
        "free_cash_flow_yoy_chg": 123
      }
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Earnings API returns the most recent SEC filings tied to a company’s earnings periods. The response is a flat list — each entry IS one filing (e.g. the initial 8-K earnings release, or a later 10-Q / 10-K / 20-F) — sorted by (report_period DESC, filing_date ASC). Each entry includes:
  • Key income statement fields (e.g. revenue, net income, EPS)
  • Key balance sheet fields (e.g. cash, debt, assets, liabilities)
  • Key cash flow fields (e.g. operating cash flow, capex, free cash flow)
  • Analyst estimate comparisons when available (e.g. estimated revenue / EPS and BEAT/MISS/MEET)
Each entry can include both quarterly and annual data. Free tier: Requests for AAPL, MSFT, NVDA, TSLA, and GOOGL do not require credits. Important: This endpoint returns figures from a company’s initial earnings release, typically filed as an 8-K with the SEC. Because an 8-K is a preliminary snapshot, some fields may be null — this simply means the company did not report that figure in its initial release. Full financial statements (income statements, balance sheets, and cash flow statements) are published later via 10-K and 10-Q filings and can be retrieved through our /financials endpoint. Real-time availability: For non-Enterprise customers, real-time earnings are currently available only for companies in the S&P 500.

​
Available Tickers

You can fetch a list of available tickers with a GET request to: https://api.financialdatasets.ai/earnings/tickers/

​
Getting Started

There are only 3 steps for making a successful API call:
  1. Add your API key to the header of the request as X-API-KEY.
  2. Add the required query param ticker.
  3. Execute the API request.

​
Example

Earnings
import requests

headers = {
    "X-API-KEY": "your_api_key_here"
}

ticker = "AAPL"
url = f"https://api.financialdatasets.ai/earnings?ticker={ticker}"

response = requests.get(url, headers=headers)
data = response.json()
earnings = data["earnings"]

​
Notes

  • The top-level earnings is a flat list of filings sorted by (report_period DESC, filing_date ASC). With limit=N, up to N report-periods worth of filings are returned — the entry count may exceed N when a recent period has both an 8-K and a 10-Q/10-K.
  • report_period repeats across consecutive entries when one period has multiple filings (e.g. the initial 8-K earnings release followed by the later 10-Q). The 8-K appears first because it has the earlier filing_date.
  • filing_date and filing_datetime are both expressed in Eastern Time (the SEC’s operating timezone). filing_datetime is the precise sub-day moment SEC accepted the filing; filing_date is its calendar day.
  • An 8-K is preliminary, so its quarterly / annual blocks may omit fields the company didn’t disclose at release time. The matching 10-Q / 10-K typically fills those in. For complete financials, use the /financials endpoint.
  • quarterly and annual may be omitted from an entry when data isn’t available for that time dimension.
  • Estimate fields (and BEAT/MISS/MEET) are returned only when analyst estimates are available. *_chg fields (e.g. revenue_chg, net_income_chg) are returned only when calculable.
  • Sources are limited to SEC filings: 8-K, 10-Q, 10-K, and 20-F.

Authorizations

​
X-API-KEY
string
header
required

API key for authentication.

Query Parameters

​
ticker
string
required

The ticker symbol (e.g. AAPL).

​
limit
integer
default:1

Number of most-recent report periods worth of filings to return, sorted by (report_period DESC, filing_date ASC). The number of entries returned may exceed limit when a recent period has both an 8-K and a 10-Q / 10-K. Values above 40 are clamped to 40. Non-positive or non-integer values return 400.

Required range: 1 <= x <= 40

Response

Earnings response

​
earnings
object[]

Flat list of SEC filings for the ticker, sorted by (report_period DESC, filing_date ASC). When limit=N, up to N report_periods worth of filings are returned; entry count may exceed N when a recent period has both an 8-K and a 10-Q/10-K.