Company Earnings

Get earnings snapshot

curl --request GET \
  --url https://api.financialdatasets.ai/earnings \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.financialdatasets.ai/earnings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.financialdatasets.ai/earnings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.financialdatasets.ai/earnings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.financialdatasets.ai/earnings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "MARGIN_EXPANSION",
          "headline": "<string>",
          "metric": "<string>",
          "period": "<string>",
          "details": {}
        }
      ],
      "quarterly": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 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,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 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
      }
    }
  ],
  "next_page_url": "<string>"
}

{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}

{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription. Please upgrade your plan."
}

{
  "error": "Not Found",
  "message": "Ticker XXXX not found"
}

GET

earnings

Get earnings snapshot

curl --request GET \
  --url https://api.financialdatasets.ai/earnings \
  --header 'X-API-KEY: <api-key>'

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.financialdatasets.ai/earnings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.financialdatasets.ai/earnings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.financialdatasets.ai/earnings"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.financialdatasets.ai/earnings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "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": "MARGIN_EXPANSION",
          "headline": "<string>",
          "metric": "<string>",
          "period": "<string>",
          "details": {}
        }
      ],
      "quarterly": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 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,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 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
      }
    }
  ],
  "next_page_url": "<string>"
}

{
  "error": "Bad Request",
  "message": "Invalid request parameters"
}

{
  "error": "Unauthorized",
  "message": "Invalid API key provided"
}

{
  "error": "Payment Required",
  "message": "This endpoint requires a paid subscription. Please upgrade your plan."
}

{
  "error": "Not Found",
  "message": "Ticker XXXX not found"
}

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. 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/

Getting Started

There are only 3 steps for making a successful API call:

Add your API key to the header of the request as X-API-KEY.
Add the required query param ticker.
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.
*_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. This is the total across all pages, not a page size: each page holds up to 10 records, linked by next_page_url.

Required range: 1 <= x <= 40

cursor

string

Opaque pagination cursor from a previous response's next_page_url. When provided, all other query parameters are ignored: the cursor carries the original request's filters. Treat it as opaque; do not construct or modify it.

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.

Show child attributes

next_page_url

string

Absolute URL of the next page of results. Present only when more results remain; request it as-is to continue. Each page holds up to 10 records.

Overview

Integrations

Datasets

Guides

Overview

Coverage

Available Tickers

Getting Started

Example

Notes

Authorizations

Query Parameters

Response

​Overview

​Coverage

​Available Tickers

​Getting Started

​Example

​Notes

Authorizations

Query Parameters

Response

Overview

Coverage

Available Tickers

Getting Started

Example

Notes