> ## 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. # Company Earnings > Get quarterly and annual earnings data for a single company. Includes EPS actuals, estimates, surprise, and report dates. ### 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) Each entry can include both `quarterly` and `annual` data. **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](/api/financials/income-statements). **Real-time availability**: For non-Enterprise customers, real-time earnings are currently available only for companies in the S\&P 500. ### Coverage | Tickers | Years of Coverage | Updated | | ------- | ----------------- | ---------------- | | 6,000+ | 2+ years | Within 5 seconds | ### Available Tickers You can fetch a list of available tickers with a `GET` request to: [https://api.financialdatasets.ai/earnings/tickers/](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 ```python Earnings theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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](/api/financials/income-statements). * `quarterly` and `annual` may be omitted from an entry when data isn't available for that time dimension. * `*_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`. ## OpenAPI ````yaml GET /earnings openapi: 3.0.1 info: title: Financial Datasets API description: >- Stock market API with real-time and historical financial data for 27,000+ tickers over 30+ years. Financial statements, equity prices, insider trades, SEC filings, and more. version: 1.0.0 license: name: MIT url: https://opensource.org/licenses/MIT contact: name: API Support url: mailto:support@financialdatasets.ai email: support@financialdatasets.ai termsOfService: https://financialdatasets.ai/terms-of-use servers: - url: https://api.financialdatasets.ai/ description: Production server security: - X-API-KEY: [] tags: - name: Financial Statements description: Access to income statements, balance sheets, and cash flow statements - name: Market Data description: Real-time and historical price data - name: Company Information description: Company facts like ticker, name, and description - name: Earnings description: Earnings data and related information - name: News description: Real-time and historical news articles - name: SEC Filings description: SEC filings and regulatory documents - name: Insider Trades description: Insider trading activity and transactions - name: Activist Ownership description: Activist stakes from SEC Schedule 13D filings, in real time - name: Beneficial Ownership description: >- Holders of more than 5% of a company's shares, from SEC Schedules 13D and 13G - name: Insider Ownership description: Insider ownership statements from SEC Forms 3 and 5 - name: Institutional Holdings description: SEC-direct 13F equity holdings of institutional investment managers - name: Index Funds description: >- ETF and index-fund holdings, weights, and the funds that hold a given security - name: Financial Metrics description: Financial ratios, metrics, and key performance indicators - name: Macroeconomics description: Real-time and historical macroeconomic data like interest rates - name: KPIs description: Sector-specific operational KPIs extracted from earnings releases. paths: /earnings: get: tags: - Earnings summary: Get earnings snapshot description: >- Get the most recent earnings snapshot for a ticker. Optional estimate/surprise and change fields are returned only when available. operationId: getEarnings parameters: - name: ticker in: query description: The ticker symbol (e.g. `AAPL`). required: true schema: type: string - name: limit in: query description: >- 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: false schema: type: integer minimum: 1 maximum: 40 default: 1 responses: '200': description: Earnings response content: application/json: schema: $ref: '#/components/schemas/EarningsResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '402': $ref: '#/components/responses/PaymentRequiredError' '404': $ref: '#/components/responses/NotFoundError' components: schemas: EarningsResponse: type: object properties: earnings: type: array description: >- 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. items: $ref: '#/components/schemas/EarningsRecord' EarningsRecord: type: object properties: ticker: type: string description: The requested ticker symbol. report_period: type: string format: date description: Report period this filing covers. fiscal_period: type: string description: Fiscal period label (e.g. 2026-Q1 or 2025-FY). currency: type: string description: ISO currency code (e.g. USD). source_type: type: string description: The SEC form type backing this filing. enum: - 8-K - 10-Q - 10-K - 20-F filing_date: type: string format: date description: >- Calendar day SEC accepted the filing, in Eastern Time (the SEC's operating timezone). Calendar-day pair to `filing_datetime`. filing_datetime: type: string format: date-time nullable: true description: >- Sub-day timestamp recording when SEC accepted the filing, in Eastern Time. Sourced from SEC's `acceptanceDateTime` field on the EDGAR submissions API. Pairs with `filing_date` (calendar-day precision of the same event). filing_window: type: string nullable: true description: >- Market session at the moment SEC accepted the filing, evaluated in Eastern Time. PRE_MARKET = weekday 04:00–09:30 ET. DURING_MARKET = weekday 09:30–16:00 ET. AFTER_HOURS = weekday outside regular trading hours. WEEKEND = Saturday or Sunday. Null when filing_datetime is unavailable. enum: - PRE_MARKET - DURING_MARKET - AFTER_HOURS - WEEKEND signals: type: array description: >- Curated, market-moving insights distilled from this filing. Each item has a pre-rendered `headline`, structured `details`, and an `importance` ranking. Returned only when at least one signal fires for this entry; field is omitted otherwise. Capped at 8 per entry, ordered HIGH → MEDIUM → LOW. items: $ref: '#/components/schemas/Signal' filing_url: type: string format: uri description: URL to the SEC filing. accession_number: type: string description: SEC accession number identifying the filing. quarterly: $ref: '#/components/schemas/EarningsTimeDimension' description: Quarterly figures from this filing. Returned only when available. annual: $ref: '#/components/schemas/EarningsTimeDimension' description: Annual figures from this filing. Returned only when available. required: - ticker - report_period - source_type - filing_date - filing_url - accession_number ErrorResponse: type: object properties: error: type: string description: A short error message. message: type: string description: A more detailed error message. Signal: type: object description: >- A curated market-moving insight derived from this filing. Pre-rendered `headline` is suitable for direct display; `details` carries structured fields for filtering and programmatic use. Signals are returned in priority order (most material first); the `type` itself encodes magnitude (e.g. `STRONG_REVENUE_INCREASE` vs `REVENUE_INCREASE`). required: - type - headline properties: type: type: string description: >- Signal category. EPS_BEAT/EPS_MISS: actual EPS vs analyst estimate. REVENUE_BEAT/REVENUE_MISS: actual revenue vs estimate. MARGIN_EXPANSION/MARGIN_CONTRACTION: any of gross/operating/net margin moved year-over-year by ≥100bps. GUIDANCE_RAISED/GUIDANCE_LOWERED/GUIDANCE_REAFFIRMED/GUIDANCE_INITIATED: forward-looking guidance change reported in the filing. SEGMENT_OUTPERFORMANCE/SEGMENT_UNDERPERFORMANCE: best- or worst-performing reportable segment by organic revenue growth. NON_GAAP_DIVERGENCE: an adjusted/non-GAAP figure differs materially from its GAAP counterpart on the same period. BACKLOG_SURGE/BACKLOG_DECLINE: backlog or remaining performance obligations moved year-over-year by ≥20%. REVENUE_INCREASE/STRONG_REVENUE_INCREASE and DECLINE variants: tiered year-over-year revenue change (≥10% / ≥20% magnitude). NET_INCOME_INCREASE/STRONG_NET_INCOME_INCREASE and DECLINE variants: tiered year-over-year net income change (≥15% / ≥30%). EPS_INCREASE/STRONG_EPS_INCREASE and DECLINE variants: tiered year-over-year EPS change (≥15% / ≥30%); independent from net income because share buybacks can amplify EPS movement. CAPEX_INCREASE/STRONG_CAPEX_INCREASE and DECLINE variants: tiered year-over-year capital expenditure change in spending magnitude (≥15% / ≥30%). enum: - EPS_BEAT - EPS_MISS - REVENUE_BEAT - REVENUE_MISS - MARGIN_EXPANSION - MARGIN_CONTRACTION - GUIDANCE_RAISED - GUIDANCE_LOWERED - GUIDANCE_REAFFIRMED - GUIDANCE_INITIATED - SEGMENT_OUTPERFORMANCE - SEGMENT_UNDERPERFORMANCE - NON_GAAP_DIVERGENCE - BACKLOG_SURGE - BACKLOG_DECLINE - REVENUE_INCREASE - REVENUE_DECLINE - STRONG_REVENUE_INCREASE - STRONG_REVENUE_DECLINE - NET_INCOME_INCREASE - NET_INCOME_DECLINE - STRONG_NET_INCOME_INCREASE - STRONG_NET_INCOME_DECLINE - EPS_INCREASE - EPS_DECLINE - STRONG_EPS_INCREASE - STRONG_EPS_DECLINE - CAPEX_INCREASE - CAPEX_DECLINE - STRONG_CAPEX_INCREASE - STRONG_CAPEX_DECLINE metric: type: string nullable: true description: >- The metric this signal references, when applicable (e.g. `revenue`, `earnings_per_share`, `operating_margin`, or a guidance/KPI metric name). period: type: string nullable: true description: >- The fiscal period the signal references (e.g. `2026-Q1`, `FY 2026`). Forward guidance signals reference the guided period; financial signals reference the reporting period of this filing. headline: type: string description: Pre-rendered, human-readable summary suitable for direct display. details: type: object description: >- Structured fields specific to the signal type. Contents vary: surprise signals carry `actual`, `estimate`, `surprise_pct`; guidance signals carry `low`, `high`, `point_estimate`, `prior_value`, `revision_pct`; segment signals carry `best`, `worst`, `spread_pp`; non-GAAP signals carry `gaap_field`, `non_gaap_value`, `gaap_value`, `divergence_pct`; growth signals carry `current`, `yoy_chg`. Null values are omitted. Refer to type-specific examples. additionalProperties: true EarningsTimeDimension: type: object properties: revenue: type: number nullable: true revenue_chg: type: number description: >- Percentage change in revenue versus the prior period as a decimal (e.g. 0.10 = +10%). Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. revenue_yoy_chg: type: number description: >- Year-over-year change in revenue versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. estimated_revenue: type: number description: >- Consensus analyst estimate for revenue. Returned only when available. revenue_surprise: type: string description: >- Revenue surprise classification versus estimate. Returned only when available. enum: - BEAT - MISS - MEET revenue_surprise_pct: type: number description: >- Signed magnitude of the revenue surprise as a decimal (e.g. 0.0196 = revenue came in 1.96% above estimate). Returned only when an estimate is available. earnings_per_share: type: number nullable: true earnings_per_share_chg: type: number description: >- Percentage change in EPS versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. earnings_per_share_yoy_chg: type: number description: >- Year-over-year change in EPS versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. estimated_earnings_per_share: type: number description: >- Consensus analyst estimate for diluted earnings per share. Returned only when available. eps_surprise: type: string description: >- EPS surprise classification versus estimate. Returned only when available. enum: - BEAT - MISS - MEET eps_surprise_pct: type: number description: >- Signed magnitude of the EPS surprise as a decimal (e.g. 0.5652 = EPS came in 56.52% above estimate). Returned only when an estimate is available. gross_profit: type: number nullable: true gross_profit_chg: type: number description: >- Percentage change in gross profit versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. gross_profit_yoy_chg: type: number description: >- Year-over-year change in gross profit versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. gross_margin: type: number description: >- Gross margin as a decimal (gross_profit / revenue). Returned only when calculable. gross_margin_chg_bps: type: number description: >- Absolute change in gross margin versus the prior period in basis points (e.g. 200.0 = margin expanded 200 bps). Returned only when calculable. gross_margin_chg_pct: type: number description: >- Percentage change in gross margin versus the prior period as a decimal. Returned only when calculable. gross_margin_yoy_chg_bps: type: number description: >- Year-over-year change in gross margin versus the same fiscal quarter one year prior, in basis points. Quarterly payload only. Returned only when calculable. gross_margin_yoy_chg_pct: type: number description: >- Year-over-year percentage change in gross margin versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. operating_income: type: number nullable: true operating_income_chg: type: number description: >- Percentage change in operating income versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. operating_income_yoy_chg: type: number description: >- Year-over-year change in operating income versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. operating_margin: type: number description: >- Operating margin as a decimal (operating_income / revenue). Returned only when calculable. operating_margin_chg_bps: type: number description: >- Absolute change in operating margin versus the prior period in basis points. Returned only when calculable. operating_margin_chg_pct: type: number description: >- Percentage change in operating margin versus the prior period as a decimal. Returned only when calculable. operating_margin_yoy_chg_bps: type: number description: >- Year-over-year change in operating margin versus the same fiscal quarter one year prior, in basis points. Quarterly payload only. Returned only when calculable. operating_margin_yoy_chg_pct: type: number description: >- Year-over-year percentage change in operating margin versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. net_income: type: number nullable: true net_income_chg: type: number description: >- Percentage change in net income versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. net_income_yoy_chg: type: number description: >- Year-over-year change in net income versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. net_margin: type: number description: >- Net margin as a decimal (net_income / revenue). Returned only when calculable. net_margin_chg_bps: type: number description: >- Absolute change in net margin versus the prior period in basis points. Returned only when calculable. net_margin_chg_pct: type: number description: >- Percentage change in net margin versus the prior period as a decimal. Returned only when calculable. net_margin_yoy_chg_bps: type: number description: >- Year-over-year change in net margin versus the same fiscal quarter one year prior, in basis points. Quarterly payload only. Returned only when calculable. net_margin_yoy_chg_pct: type: number description: >- Year-over-year percentage change in net margin versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. weighted_average_shares: type: number nullable: true weighted_average_shares_diluted: type: number nullable: true cash_and_equivalents: type: number nullable: true change_in_cash_and_equivalents: type: number nullable: true total_debt: type: number nullable: true total_assets: type: number nullable: true total_liabilities: type: number nullable: true shareholders_equity: type: number nullable: true net_cash_flow_from_operations: type: number nullable: true net_cash_flow_from_operations_chg: type: number description: >- Percentage change in net cash flow from operations versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. net_cash_flow_from_operations_yoy_chg: type: number description: >- Year-over-year change in net cash flow from operations versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. net_cash_flow_from_investing: type: number nullable: true net_cash_flow_from_investing_chg: type: number description: >- Percentage change in net cash flow from investing versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. net_cash_flow_from_investing_yoy_chg: type: number description: >- Year-over-year change in net cash flow from investing versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. net_cash_flow_from_financing: type: number nullable: true net_cash_flow_from_financing_chg: type: number description: >- Percentage change in net cash flow from financing versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. net_cash_flow_from_financing_yoy_chg: type: number description: >- Year-over-year change in net cash flow from financing versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. capital_expenditure: type: number nullable: true capital_expenditure_chg: type: number description: >- Percentage change in capital expenditure versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. capital_expenditure_yoy_chg: type: number description: >- Year-over-year change in capital expenditure versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. free_cash_flow: type: number nullable: true free_cash_flow_chg: type: number description: >- Percentage change in free cash flow versus the prior period as a decimal. Sequential in the quarterly payload, year-over-year in the annual payload. Returned only when calculable. free_cash_flow_yoy_chg: type: number description: >- Year-over-year change in free cash flow versus the same fiscal quarter one year prior, as a decimal. Quarterly payload only. Returned only when calculable. responses: BadRequestError: description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Bad Request message: Invalid request parameters UnauthorizedError: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized message: Invalid API key provided PaymentRequiredError: description: The request requires a paid subscription content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Payment Required message: >- This endpoint requires a paid subscription. Please upgrade your plan. NotFoundError: description: The specified resource was not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Not Found message: Ticker XXXX not found securitySchemes: X-API-KEY: type: apiKey name: X-API-KEY description: API key for authentication. in: header ````