> ## 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. # Earnings Feed > A real-time feed of the most recently filed earnings across all covered companies. ### 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](/api/earnings/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. ### Coverage | Tickers | Years of Coverage | Updated | | ------- | ----------------- | ---------------- | | 6,000+ | 2+ years | Within 5 seconds | ### 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 ```python Earnings Feed theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}} 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. ## 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: 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 ````