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 Feed returns the most recent earnings filings across all covered companies, sorted by SEC filing date (newest first). Use it to power dashboards, alerts, or any view of “what just got reported.” Each entry follows the same EarningsRecord shape as the company-earnings response — see Earnings for the full field reference. The feed sorts by filing_date descending (most recently filed first) and dedupes by (ticker, report_period). As a company progresses from its initial 8-K earnings release to the full 10-Q or 10-K filing, the entry updates to reflect the most complete data available.

​
Getting Started

Call GET /earnings/ without the ticker query param:
  1. Add your API key to the header of the request as X-API-KEY.
  2. Optionally provide limit (default 10, max 100).
  3. Execute the API request.

​
Example

Earnings Feed
import requests

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

# Top 10 most recently filed earnings across all companies
url = "https://api.financialdatasets.ai/earnings/"

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

​
Notes

  • Sort order: items are returned newest-first by SEC filing_date.
  • Dedup: each (ticker, report_period) appears once per response. When both an 8-K earnings release and the corresponding 10-Q/10-K are available, the more complete filing is shown.
  • source_type: identifies the underlying SEC form — 8-K (preliminary earnings release), 10-Q (quarterly), 10-K (annual), or 20-F (foreign annual).
  • Polling: results are cached briefly server-side; expect near-real-time freshness as new filings land.

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.