Earnings Feed - Financial Datasets

Get earnings snapshot

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

import requests

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

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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))

}

HttpResponse<String> response = Unirest.get("https://api.financialdatasets.ai/earnings")
  .header("X-API-KEY", "<api-key>")
  .asString();

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",
      "filing_date": "2023-12-25",
      "filing_url": "<string>",
      "accession_number": "<string>",
      "fiscal_period": "<string>",
      "currency": "<string>",
      "filing_datetime": "2023-11-07T05:31:56Z",
      "signals": [
        {
          "headline": "<string>",
          "metric": "<string>",
          "period": "<string>",
          "details": {}
        }
      ],
      "quarterly": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "estimated_revenue": 123,
        "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_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_pct": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 123,
        "estimated_earnings_per_share": 123,
        "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
      }
    }
  ]
}

{
  "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>'

import requests

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

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

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))

}

HttpResponse<String> response = Unirest.get("https://api.financialdatasets.ai/earnings")
  .header("X-API-KEY", "<api-key>")
  .asString();

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",
      "filing_date": "2023-12-25",
      "filing_url": "<string>",
      "accession_number": "<string>",
      "fiscal_period": "<string>",
      "currency": "<string>",
      "filing_datetime": "2023-11-07T05:31:56Z",
      "signals": [
        {
          "headline": "<string>",
          "metric": "<string>",
          "period": "<string>",
          "details": {}
        }
      ],
      "quarterly": {
        "revenue": 123,
        "revenue_chg": 123,
        "revenue_yoy_chg": 123,
        "estimated_revenue": 123,
        "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_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_pct": 123,
        "earnings_per_share": 123,
        "earnings_per_share_chg": 123,
        "earnings_per_share_yoy_chg": 123,
        "estimated_earnings_per_share": 123,
        "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
      }
    }
  ]
}

{
  "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 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.

Coverage

Tickers	Years of Coverage	Updated
6,000+	2+ years	Within 5 seconds

Getting Started

Call GET /earnings/ without the ticker query param:

Add your API key to the header of the request as X-API-KEY.
Optionally provide limit (default 10, max 100).
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.

Show child attributes

Company Earnings Historical

​Overview

​Coverage

​Getting Started

​Example

​Notes