TutorialEarnings Calendar APIUpcoming EarningsEPS Estimates

Earnings Calendar API: Developer Guide

Q: How do I find upcoming earnings dates programmatically?

Call /api/earnings/upcoming with days=N (1 to 28, default 7). The response is paginated and sorted by earnings date ascending; each row carries a symbols array (a multi-class issuer is one entry with all its tickers), the issuer name, the predicted earnings and filing dates, filing type, and the consensus estimate fields when available. For a watchlist of known symbols, use /api/earnings/calendar with up to 50 tickers per call. For a single symbol, use /api/earnings/date.

Q: How do I get historical EPS through the earnings API?

Call /api/earnings/eps-history with symbol, period (quarter, annual, or ttm), and limit. The response contains basic EPS, diluted EPS, net income, the basic and diluted weighted-average share counts, and a pre-computed epsGrowth (year-over-year in annual mode, quarter-over-quarter in quarterly mode). Values come from income-statement XBRL in each 10-K, 10-Q, or 20-F and are split-adjusted by default.

Q: How do I get dividend history and payout ratios from the API?

Call /api/earnings/dividend-history with symbol, period, and limit. Each period returns dividend per share, total dividends paid, payout ratio (dividends / net income), dividend coverage (operating cash flow / dividends), and year-over-year dividend growth. Non-dividend-paying companies return null values, so you can tell "never paid" apart from missing data. The endpoint is on the free tier.

The StockFit Earnings Calendar API: upcoming earnings dates, consensus EPS estimates, and report times across US issuers, plus EPS history and 8-K prints.

Published May 11, 202613 min readStockFit Engineering

This guide walks the StockFit earnings calendar API end to end, then the rest of the earnings toolkit that hangs off it: upcoming earnings dates with analyst consensus EPS estimates and expected report time, the per-symbol date lookup, batch watchlist lookups, the earnings snapshot, EPS and dividend history, multi-year trends, line-item growth, earnings quality, and the 8-K Item 2.02 print stream. Every JSON block below is a real production response keyed on NVIDIA (NVDA), whose next report is expected on August 26, 2026, pulled from the live API on July 9, 2026.

If you are building an earnings watcher, a screener, an analyst tool, or a strategy that trades around earnings, this is the full set of endpoints you need. Each section gives the cURL call, the live response, and what to do with it. Tier coverage is at the bottom.

The earnings calendar API and the earnings toolkit

Everything lives under /api/earnings/*. The earnings calendar API is three of those endpoints (/upcoming, /calendar, /date), all of which now return the consensus EPS estimate and expected report time alongside the predicted date. The rest of the earnings API covers history, snapshot, trends, and quality. The 8-K Item 2.02 stream is on /api/filings/latest with event=earnings, and line-item growth lives on /api/financials/growth.

text

/api/earnings/upcoming          Earnings calendar API: market-wide upcoming reports (1-28 day window)
/api/earnings/calendar          Earnings calendar API: batch lookup, up to 50 tickers per call
/api/earnings/date              Earnings calendar API: single-ticker next date + estimate
/api/earnings/snapshot          One-call summary (EPS, revenue, margins, returns, Z/F-score)
/api/earnings/eps-history       Quarterly or annual EPS series with basic/diluted share counts
/api/earnings/dividend-history  Dividend per share, payout ratio, coverage, growth
/api/earnings/trends            3yr/5yr CAGRs, margin direction, quality ratios
/api/earnings/chart/eps         Chart-ready EPS, net income, and net margin series
/api/earnings/chart/quality     Chart-ready net income vs operating cash flow

/api/financials/growth          Line-item growth (revenue, gross, operating, net, FCF)
/api/filings/latest             Filings stream, filter event=earnings for 8-K Item 2.02
/api/filings/item               Extract Item 2.02 body as HTML or plain text

One convention to know before reading the responses below: margins, returns (ROE, ROIC), and multi-year CAGRs are expressed as percentages (grossMargin 71.07 means 71.07%), while growth rates and chart ratios are decimals (revenueGrowth 0.6547 means 65.47%). Each field states its unit in its Swagger description.

The earnings calendar API: upcoming, calendar, date

The earnings calendar API answers two questions in one call: who reports next? and what is the Street expecting? All three endpoints share the same prediction engine (each issuer's historical SEC filing cadence, cross-checked against a corporate earnings-calendar feed) and each returns the analyst consensus EPS estimate, the number of estimates behind it, and the expected report time when they are available.

/api/earnings/upcoming: the market-wide calendar

/api/earnings/upcoming returns every US-listed issuer expected to report within the next N days (default 7, max 28), sorted by earnings date ascending. Paginated. Companies in their first year of reporting (no prior cadence to learn from) and delisted names are excluded. Each row keys on a symbols array, primary first, so a multi-class issuer like Alphabet is a single entry carrying both GOOGL and GOOG rather than two duplicate rows, plus the issuer name for display.

bash

curl 'https://api.stockfit.io/v1/api/earnings/upcoming?days=14&pageSize=15' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "page": 1,
  "pageSize": 15,
  "totalPages": 33,
  "totalResults": 488,
  "data": [
    { "symbols": ["PEP"],  "name": "PEPSICO INC",                   "earningsDate": "2026-07-09", "filingDate": "2026-07-09", "filingType": "10-Q", "epsEstimate": 2.19, "numEstimates": 7, "reportTime": "pre_market" },
    { "symbols": ["WDFC"], "name": "WD 40 CO",                      "earningsDate": "2026-07-09", "filingDate": "2026-07-09", "filingType": "10-Q", "epsEstimate": 1.58, "numEstimates": 2, "reportTime": "after_hours" },
    { "symbols": ["DAL"],  "name": "DELTA AIR LINES, INC.",         "earningsDate": "2026-07-10", "filingDate": "2026-07-10", "filingType": "10-Q", "epsEstimate": 1.5,  "numEstimates": 7, "reportTime": "pre_market" },
    { "symbols": ["ARTW"], "name": "ARTS WAY MANUFACTURING CO INC", "earningsDate": "2026-07-09", "filingDate": "2026-07-13", "filingType": "10-Q" }
  ]
}

488 expected filings in the next 14 days, four shown. Each row carries the issuer name, so a calendar view renders without a second lookup. PepsiCo carries a $2.19 consensus from 7 analysts and reports pre-market; the thinly covered small-cap ARTW has no analyst coverage, so epsEstimate, numEstimates, and reportTime are simply absent rather than null. Note that filingDate can trail earningsDate: ARTW is expected to announce on July 9 but file the 10-Q on July 13. Typical use: refresh the calendar overnight, then fan out per-symbol requests for the rest of the earnings API.

/api/earnings/calendar: batch lookup for a watchlist

When you already know the symbols, use /api/earnings/calendar for up to 50 tickers in one request. The response is a map keyed by symbol; each value carries the same fields as an /upcoming row. Delisted companies (no active listing on any exchange) map to null. This is the right call shape for keeping a static watchlist's earnings dates and estimates up to date.

bash

curl 'https://api.stockfit.io/v1/api/earnings/calendar?symbols=NVDA,AAPL,MSFT,GOOGL' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "NVDA":  { "earningsDate": "2026-08-26", "filingDate": "2026-08-26", "filingType": "10-Q" },
  "AAPL":  { "earningsDate": "2026-07-30", "filingDate": "2026-07-31", "filingType": "10-Q", "epsEstimate": 1.88, "numEstimates": 11, "reportTime": "after_hours" },
  "MSFT":  { "earningsDate": "2026-07-29", "filingDate": "2026-07-29", "filingType": "10-Q", "epsEstimate": 4.21, "numEstimates": 15 },
  "GOOGL": { "earningsDate": "2026-07-22", "filingDate": "2026-07-23", "filingType": "10-Q", "epsEstimate": 2.86, "numEstimates": 11 }
}

Apple reports after hours with a $1.88 consensus from 11 analysts; Microsoft and Alphabet carry consensus figures but no confirmed report time yet, so reportTime is omitted. NVDA has a predicted date but no consensus this far out, so its estimate fields are absent until closer to the print.

/api/earnings/date: single-ticker next date

For one symbol, /api/earnings/date returns the next predicted earnings and filing date, plus the estimate fields when they exist.

bash

curl 'https://api.stockfit.io/v1/api/earnings/date?symbol=NVDA' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "symbol": "NVDA",
  "earningsDate": "2026-08-26",
  "filingDate": "2026-08-26"
}

Predicted dates come from each issuer's historical filing cadence (when last year's same-quarter 10-Q hit EDGAR, plus or minus fiscal-calendar drift), enriched by the corporate calendar feed. For large- and mid-cap issuers the prediction lands within a few business days of the actual filing. First-time filers are excluded from /upcoming because there is no prior cadence to fit. For how that prediction is confirmed against exchange data inside the near-term window, and how to tell a confirmed date from a predicted one, see accurate earnings dates: predict, then confirm.

Consensus EPS estimates and expected report time

Three optional fields ride on every earnings calendar API response. epsEstimate is the analyst consensus EPS for the upcoming report, numEstimates is how many analyst estimates stand behind it (a breadth signal: a $2.19 consensus from 7 analysts is firmer than one from a single analyst), and reportTime is pre_market or after_hours. All three are omitted rather than nulled when unavailable, which happens for thinly covered names and for reports still weeks out.

One basis caveat matters here: epsEstimate is a Street consensus on an adjusted (operating) basis, so treat it as what the market expects, not as a GAAP number. It will not line up one-for-one with the GAAP diluted EPS in /api/earnings/eps-history, which is parsed straight from XBRL and can diverge materially for companies with large stock-comp, amortization, or one-off items. Use reportTime to schedule around the print, the estimate to gauge what is priced in, and eps-history for the clean GAAP actual once the filing lands.

Earnings snapshot endpoint

/api/earnings/snapshot returns the latest annual fundamentals as a single object: EPS, revenue, three margins, three returns, free cash flow, growth rates, Piotroski F-Score, Altman Z-Score, and the next expected earnings date. One call per symbol, useful for screening 500 tickers without 500 follow-ups.

bash

curl 'https://api.stockfit.io/v1/api/earnings/snapshot?symbol=NVDA' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "symbol": "NVDA",
  "period": "2026-01-31",
  "fiscalYear": 2026,
  "fiscalPeriod": "FY",
  "eps": 4.93,
  "epsDiluted": 4.9,
  "netIncome": 120067000000,
  "revenue": 215938000000,
  "grossMargin": 71.07,
  "operatingMargin": 60.38,
  "netMargin": 55.6,
  "roe": 101.49,
  "roic": 92.57,
  "freeCashFlow": 96676000000,
  "fcfToNetIncome": 80.52,
  "revenueGrowth": 0.6547,
  "epsGrowth": 0.6599,
  "netIncomeGrowth": 0.6475,
  "piotroskiFScore": 4,
  "altmanZScore": 6.71,
  "altmanZone": "safe",
  "nextEarningsDate": "2026-08-26",
  "nextFilingDate": "2026-08-26"
}

For NVDA, the latest FY ended 2026-01-31 with $215.9B revenue, 60.4% operating margin, and 66% YoY EPS growth. Z-Score 6.71 is well inside the safe zone; F-Score 4 (range 0-9) flags that the strength is concentrated in profitability and growth rather than working-capital conservatism. The snapshot also carries nextEarningsDate, so a single screening call gives you both the fundamentals and the next date on the calendar.

EPS history endpoint

/api/earnings/eps-history returns the quarterly or annual EPS series. Period options: annual, quarter, or ttm for a single trailing-twelve-months figure. Each row carries basic and diluted EPS, net income, the basic and diluted weighted-average share counts (sharesOutstanding and sharesOutstandingDiluted), and epsGrowth, which is the change versus the previous period in the series (quarter-over-quarter for period=quarter, year-over-year for period=annual). Values are mapped from income-statement XBRL in each 10-K, 10-Q, and 20-F. For multi-class issuers like Visa, where no blended figure is filed, EPS and share count are reconstructed from the per-class facts, see extracting EPS and share count with Arelle.

bash

curl 'https://api.stockfit.io/v1/api/earnings/eps-history?symbol=NVDA&period=quarter&limit=6' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

[
  { "period": "2026-04-30", "fiscalYear": 2027, "fiscalPeriod": "Q1", "eps": 2.40, "epsDiluted": 2.39, "netIncome": 58321000000, "sharesOutstanding": 24286000000, "sharesOutstandingDiluted": 24391000000, "epsGrowth": 0.3559 },
  { "period": "2026-01-31", "fiscalYear": 2026, "fiscalPeriod": "Q4", "eps": 1.77, "epsDiluted": 1.76, "netIncome": 42960000000, "sharesOutstanding": 24302208791, "sharesOutstandingDiluted": 24430307692, "epsGrowth": 0.3511 },
  { "period": "2025-10-31", "fiscalYear": 2026, "fiscalPeriod": "Q3", "eps": 1.31, "epsDiluted": 1.30, "netIncome": 31910000000, "sharesOutstanding": 24327000000, "sharesOutstandingDiluted": 24483000000, "epsGrowth": 0.213 },
  { "period": "2025-07-31", "fiscalYear": 2026, "fiscalPeriod": "Q2", "eps": 1.08, "epsDiluted": 1.08, "netIncome": 26422000000, "sharesOutstanding": 24366000000, "sharesOutstandingDiluted": 24532000000, "epsGrowth": 0.4026 },
  { "period": "2025-04-30", "fiscalYear": 2026, "fiscalPeriod": "Q1", "eps": 0.77, "epsDiluted": 0.76, "netIncome": 18775000000, "sharesOutstanding": 24441000000, "sharesOutstandingDiluted": 24611000000, "epsGrowth": -0.1444 },
  { "period": "2025-01-31", "fiscalYear": 2025, "fiscalPeriod": "Q4", "eps": 0.90, "epsDiluted": 0.89, "netIncome": 22091000000, "sharesOutstanding": 24489241758, "sharesOutstandingDiluted": 24705362637, "epsGrowth": 0.1392 }
]

Diluted EPS has climbed from $0.76 in Q1 FY2026 (the quarter that absorbed NVDA's H20 inventory write-down) to $2.39 in Q1 FY2027, with net income more than tripling to $58.3B over the same four quarters. The share counts let you rebuild any per-share figure yourself or reconcile a multi-class filer. EPS and share counts are split-adjusted by default so the series stays continuous across stock splits; pass splitAdjust=false for the raw as-reported values.

For chart input shape, /api/earnings/chart/eps returns EPS, net income, and net margin pre-aligned for line charts. The response is series-oriented: a shared periods axis plus parallel series (absolute values) and rates (ratios) arrays, so no client-side alignment is needed.

bash

curl 'https://api.stockfit.io/v1/api/earnings/chart/eps?symbol=NVDA&period=annual&limit=5' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "periods": ["2022-01-31", "2023-01-31", "2024-01-31", "2025-01-31", "2026-01-31"],
  "series": [
    { "name": "EPS (Diluted)", "data": [0.39, 0.17, 1.19, 2.94, 4.9] },
    { "name": "Net Income",    "data": [9752000000, 4368000000, 29760000000, 72880000000, 120067000000] }
  ],
  "rates": [
    { "name": "Net Margin", "data": [0.3623, 0.1619, 0.4885, 0.5585, 0.556] }
  ]
}

Dividend history endpoint

/api/earnings/dividend-history returns the dividend series with the ratios that tell you whether a payout is safe: dividend per share, total cash dividends paid, payout ratio (dividends / net income), dividend coverage (operating cash flow / dividends), and year-over-year dividend growth. Non-dividend-paying companies return null values rather than an empty array, so you can distinguish “never paid” from “no data.”

bash

curl 'https://api.stockfit.io/v1/api/earnings/dividend-history?symbol=NVDA&period=annual&limit=3' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

[
  { "period": "2026-01-31", "fiscalYear": 2026, "fiscalPeriod": "FY", "dividendPerShare": 0.04, "totalDividendsPaid": 974000000, "payoutRatio": 0.0081, "dividendCoverage": 105.46, "dividendGrowth": 0.1765 },
  { "period": "2025-01-31", "fiscalYear": 2025, "fiscalPeriod": "FY", "dividendPerShare": 0.03, "totalDividendsPaid": 834000000, "payoutRatio": 0.0114, "dividendCoverage": 76.8453, "dividendGrowth": 1.125 },
  { "period": "2024-01-31", "fiscalYear": 2024, "fiscalPeriod": "FY", "dividendPerShare": 0.02, "totalDividendsPaid": 395000000, "payoutRatio": 0.0133, "dividendCoverage": 71.1139, "dividendGrowth": 0 }
]

NVDA pays a token dividend, $0.04 per share split-adjusted in FY2026 against $4.90 of diluted EPS, so the payout ratio is 0.81% and coverage is 105x. The read is that NVDA returns capital through buybacks and reinvestment, not dividends. For an income name the same three ratios tell the durability story directly: a payout ratio above 1.0 or coverage below 1.0 is the warning. Like EPS history, the per-share figures are split-adjusted by default.

Earnings trends and margin trajectory

/api/earnings/trends returns the 3yr and 5yr CAGRs for revenue, net income, EPS, and free cash flow, plus the margin trajectory with a classified direction (expanding, contracting, stable) measured against the same value three years prior.

bash

curl 'https://api.stockfit.io/v1/api/earnings/trends?symbol=NVDA' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "symbol": "NVDA",
  "latestPeriod": "2026-01-31",
  "margins": {
    "gross":     { "latest": 71.1, "threeYearAgo": 56.9, "direction": "expanding" },
    "operating": { "latest": 60.4, "threeYearAgo": 15.7, "direction": "expanding" },
    "net":       { "latest": 55.6, "threeYearAgo": 16.2, "direction": "expanding" }
  },
  "netMarginStdDev": 14.6,
  "netMarginStdDevRecent": 15,
  "historicalMaxNetMargin": 55.8,
  "cagr": {
    "revenue3yr":      100,
    "revenue5yr":       66.9,
    "netIncome3yr":    201.8,
    "netIncome5yr":     94.3,
    "eps3yr":          201.4,
    "eps5yr":           93.9,
    "freeCashFlow3yr": 193.9
  },
  "quality": {
    "fcfToNetIncome":        80.5,
    "interestCoverage":     503.4,
    "debtToOperatingIncome":  0.1,
    "roe":                   76.3
  }
}

NVDA operating margin expanded from 15.7% to 60.4% over three years. Net margin (55.6%) sits just under the historical max (55.8%), so the next print's upside is more likely to come from volume than from margin. The 3yr revenue CAGR of 100% is the unsustainable number to watch.

If you are running trends inside a backtest, every value is correct at the latest fiscal close, but only as a point-in-time signal as old as that timestamp. The point-in-time fundamentals guide covers how to unwind amendments so your simulation never reads a value disclosed after the decision timestamp.

Line-item growth via /api/financials/growth

EPS growth is a residual of revenue, margin, share count, and tax. /api/financials/growth exposes the underlying line-item growth rates (revenue, gross profit, operating income, net income, EBITDA, free cash flow, total assets, equity, operating cash flow) so you can attribute the bottom-line number to its drivers. Each value is (current - previous) / |previous| over the returned series, so period=annual gives year-over-year growth and period=quarter gives the sequential quarter-over-quarter step.

bash

curl 'https://api.stockfit.io/v1/api/financials/growth?symbol=NVDA&period=annual&limit=1' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

[
  {
    "period": "2026-01-31", "fiscalYear": 2026, "fiscalPeriod": "FY",
    "revenueGrowth": 0.6547, "grossProfitGrowth": 0.5682,
    "operatingIncomeGrowth": 0.6008, "netIncomeGrowth": 0.6475,
    "epsGrowth": 0.6599, "ebitdaGrowth": 0.6864,
    "freeCashFlowGrowth": 0.5887, "totalAssetsGrowth": 0.8531,
    "stockholdersEquityGrowth": 0.9828, "operatingCashFlowGrowth": 0.6027
  }
]

Reading FY2026 line by line: revenue +65.5%, gross profit +56.8%, operating income +60.1%, net income +64.8%, diluted EPS +66.0%, free cash flow +58.9%. Every line grew, but not evenly. Gross profit and operating income grew a little slower than revenue, a small margin give-back off FY2025's peak even as the three-year margin trajectory keeps expanding, while diluted EPS (+66.0%) outran net income (+64.8%) because buybacks trimmed the share count. Attributing the bottom line to its drivers this way beats taking EPS growth as a single opaque figure. Pass period=quarter for the sequential quarterly series.

Earnings quality endpoint

Two companies can report identical EPS while telling very different stories. The reliable one converts net income to operating cash flow near 1:1. The brittle one accrues revenue that does not land in the bank. /api/earnings/chart/quality returns chart-ready net-income-vs-cash-generation data in the same series-oriented shape as the EPS chart: a periods axis, a series array (net income, operating cash flow, free cash flow), and a rates array (FCF / net income, OCF / net income). As a single ratio, fcfToNetIncome on /api/earnings/snapshot answers the same question (NVDA: 80.5%, with the gap explained by data-center capex).

8-K Item 2.02: the live earnings print

US issuers report earnings on Form 8-K under Item 2.02, Results of Operations and Financial Condition, within minutes of market close. The earnings press release is attached as Exhibit 99.1. The matching 10-Q follows hours or days later. The official 8-K instructions on sec.gov spell out the item.

Stream all earnings 8-Ks across the market with /api/filings/latest filtered to event=earnings. The endpoint classifies 8-K items server-side, so you skip the client-side parsing.

bash

curl 'https://api.stockfit.io/v1/api/filings/latest?event=earnings&pageSize=10' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

json

{
  "page": 1, "pageSize": 10, "totalPages": 11, "totalResults": 107,
  "data": [
    {
      "type": "8-K",
      "accessionNumber": "0001193125-26-280314",
      "url": "https://www.sec.gov/Archives/edgar/data/723531/000119312526280314/payx-20260624.htm",
      "dateFiled": "2026-06-24",
      "xbrl": true,
      "amendment": false,
      "items": ["2.02", "9.01"],
      "events": ["earnings", "financial_exhibits"],
      "symbol": "PAYX",
      "companyName": "PAYCHEX INC"
    },
    {
      "type": "8-K",
      "accessionNumber": "0000815097-26-000086",
      "url": "https://www.sec.gov/Archives/edgar/data/815097/000081509726000086/ccl-20260623.htm",
      "dateFiled": "2026-06-23",
      "xbrl": true,
      "amendment": false,
      "items": ["2.02", "9.01"],
      "events": ["earnings", "financial_exhibits"],
      "symbol": "CCL",
      "companyName": "CARNIVAL CORP"
    }
  ]
}

Note the items array on each record and the direct url to the filing on EDGAR. The event filter (event=earnings) is server-side and looks at item codes, so a filing tagged with 2.02 plus 9.01 (financial exhibits) shows up exactly once in the earnings stream. Once an accession number is in hand, /api/filings/item with item=2.02 extracts the body as HTML or plain text for downstream summarization or string-matching against the prior quarter's release. The companion SEC forms field guide lists every 8-K item code we support (1.01 material agreements, 5.02 officer changes, 2.05 exit activities, etc.).

Full earnings calendar API workflow in cURL

Same API key end to end. Pipe through jq for ad-hoc filtering.

bash

# 1. Earnings calendar API: what is reporting in the next 28 days
curl 'https://api.stockfit.io/v1/api/earnings/upcoming?days=28' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY' | jq '.data[] | select(.symbols | index("NVDA"))'

# 2. Earnings calendar API: batch a watchlist with consensus estimates
curl 'https://api.stockfit.io/v1/api/earnings/calendar?symbols=NVDA,AAPL,MSFT,GOOGL' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

# 3. NVDA earnings snapshot
curl 'https://api.stockfit.io/v1/api/earnings/snapshot?symbol=NVDA' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

# 4. NVDA EPS history with share counts
curl 'https://api.stockfit.io/v1/api/earnings/eps-history?symbol=NVDA&period=quarter&limit=8' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

# 5. NVDA multi-year trends and margin trajectory
curl 'https://api.stockfit.io/v1/api/earnings/trends?symbol=NVDA' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

# 6. NVDA line-item growth (annual = year-over-year)
curl 'https://api.stockfit.io/v1/api/financials/growth?symbol=NVDA&period=annual&limit=1' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

# 7. Live 8-K Item 2.02 earnings prints across the market
curl 'https://api.stockfit.io/v1/api/filings/latest?event=earnings&pageSize=20' \
  -H 'Authorization: Bearer $STOCKFIT_API_KEY'

Node.js workflow for the earnings calendar API

Same workflow in Node.js 18+ (native fetch). Save as earnings-workflow.mjs and run with STOCKFIT_API_KEY=fl_xxx node earnings-workflow.mjs.

javascript

// earnings-workflow.mjs: exercise the StockFit earnings calendar API end to end.
const API = 'https://api.stockfit.io/v1';
const KEY = process.env.STOCKFIT_API_KEY;
if (!KEY) throw new Error('Set STOCKFIT_API_KEY');

const call = async (path) => {
  const res = await fetch(`${API}${path}`, { headers: { Authorization: `Bearer ${KEY}` } });
  if (!res.ok) throw new Error(`${res.status} ${res.statusText} on ${path}`);
  return res.json();
};

const symbol = 'NVDA';

// 1. Earnings calendar API: find the symbol in the next 28 days of reporters.
//    Rows key on a symbols[] array, so match with .includes, not === .
const upcoming = await call(`/api/earnings/upcoming?days=28&pageSize=500`);
const slot = upcoming.data.find((r) => r.symbols.includes(symbol));
console.log('upcoming →', slot ?? '(symbol not in next 28 days)');

// 2. Earnings calendar API: single-ticker next date
const date = await call(`/api/earnings/date?symbol=${symbol}`);
console.log('date →', date);

// 3. Earnings snapshot
const snap = await call(`/api/earnings/snapshot?symbol=${symbol}`);
console.log('snapshot →', {
  period: snap.period, eps: snap.eps, revenue: snap.revenue,
  operatingMargin: snap.operatingMargin, revenueGrowth: snap.revenueGrowth,
  nextEarningsDate: snap.nextEarningsDate,
});

// 4. EPS history with share counts
const eps = await call(`/api/earnings/eps-history?symbol=${symbol}&period=quarter&limit=4`);
console.log('eps-history →', eps.map((q) => ({
  fy: q.fiscalYear, fp: q.fiscalPeriod, epsDiluted: q.epsDiluted, growth: q.epsGrowth,
})));

// 5. Trends and margin trajectory
const trends = await call(`/api/earnings/trends?symbol=${symbol}`);
console.log('trends →', {
  marginsDirection: {
    gross: trends.margins.gross.direction,
    operating: trends.margins.operating.direction,
    net: trends.margins.net.direction,
  },
  revenue3yrCAGR: trends.cagr.revenue3yr,
  eps3yrCAGR: trends.cagr.eps3yr,
});

// 6. Line-item growth decomposition (annual = year-over-year)
const growth = await call(`/api/financials/growth?symbol=${symbol}&period=annual&limit=1`);
console.log('growth →', growth[0]);

// 7. Earnings 8-K stream (Item 2.02) across the market
const prints = await call(`/api/filings/latest?event=earnings&pageSize=3`);
console.log('filings/latest event=earnings →', prints.data.slice(0, 3));

Verbatim output (executed against the production API on 2026-07-09). NVDA does not appear under /upcoming?days=28 because its predicted earnings date is August 26, which is 48 days out:

text

upcoming → (symbol not in next 28 days)
date → { symbol: 'NVDA', earningsDate: '2026-08-26', filingDate: '2026-08-26' }
snapshot → {
  period: '2026-01-31',
  eps: 4.93,
  revenue: 215938000000,
  operatingMargin: 60.38,
  revenueGrowth: 0.6547,
  nextEarningsDate: '2026-08-26'
}
eps-history → [
  { fy: 2027, fp: 'Q1', epsDiluted: 2.39, growth: 0.3559 },
  { fy: 2026, fp: 'Q4', epsDiluted: 1.76, growth: 0.3511 },
  { fy: 2026, fp: 'Q3', epsDiluted: 1.3,  growth: 0.213  },
  { fy: 2026, fp: 'Q2', epsDiluted: 1.08, growth: 0.4026 }
]
trends → {
  marginsDirection: { gross: 'expanding', operating: 'expanding', net: 'expanding' },
  revenue3yrCAGR: 100,
  eps3yrCAGR: 201.4
}
growth → {
  period: '2026-01-31', fiscalYear: 2026, fiscalPeriod: 'FY',
  revenueGrowth: 0.6547, grossProfitGrowth: 0.5682,
  operatingIncomeGrowth: 0.6008, netIncomeGrowth: 0.6475,
  epsGrowth: 0.6599, ebitdaGrowth: 0.6864,
  freeCashFlowGrowth: 0.5887, totalAssetsGrowth: 0.8531,
  stockholdersEquityGrowth: 0.9828, operatingCashFlowGrowth: 0.6027
}
filings/latest event=earnings → [
  {
    type: '8-K',
    accessionNumber: '0001193125-26-280314',
    dateFiled: '2026-06-24',
    items: [ '2.02', '9.01' ],
    events: [ 'earnings', 'financial_exhibits' ],
    symbol: 'PAYX',
    companyName: 'PAYCHEX INC'
  },
  {
    type: '8-K',
    accessionNumber: '0000815097-26-000086',
    dateFiled: '2026-06-23',
    items: [ '2.02', '9.01' ],
    events: [ 'earnings', 'financial_exhibits' ],
    symbol: 'CCL',
    companyName: 'CARNIVAL CORP'
  },
  {
    type: '8-K',
    accessionNumber: '0001628280-26-045034',
    dateFiled: '2026-06-24',
    items: [ '2.02', '7.01', '8.01', '9.01' ],
    events: [ 'earnings', 'reg_fd', 'other', 'financial_exhibits' ],
    symbol: 'DAKT',
    companyName: 'DAKTRONICS INC /SD/'
  }
]

Earnings calendar API tier coverage

Endpoint access by subscription tier. The earnings calendar API endpoints (/upcoming, /calendar) require Stock or higher; the single-ticker /date is on Starter. EPS history, dividend history, and the chart endpoints are free.

Free: /api/earnings/eps-history, /api/earnings/dividend-history, /api/earnings/chart/eps, /api/earnings/chart/quality.
Starter ($15/mo): adds /api/earnings/snapshot, /api/earnings/date, /api/financials/growth, and /api/filings/latest.
Stock ($39/mo): unlocks the full earnings calendar API and the rest of the earnings API: /api/earnings/upcoming, /api/earnings/calendar, /api/earnings/trends, and /api/filings/item for 8-K Item 2.02 body extraction.
Professional ($69/mo): the union of every tier, all earnings and financial-data endpoints included.

Free signup at . No credit card required.

Earnings calendar API via MCP for AI agents

Every endpoint above is also registered as an MCP tool. The same API key works as both a REST key and an MCP key, so Claude Desktop, Claude Code, Cursor, and VS Code agents can call earnings_upcoming, earnings_calendar, earnings_date, earnings_snapshot, etc. directly. No separate plan, no SDK glue. Setup details at /mcp.

The same endpoints are also reachable from ChatGPT via the StockFit ChatGPT app, so you can ask about upcoming earnings in plain language without writing any code.

FAQ

What is an earnings calendar API?

An earnings calendar API returns the predicted earnings report dates for public companies. The StockFit earnings calendar API has three endpoints: /api/earnings/upcoming for the market-wide list of companies reporting in the next 1 to 28 days, /api/earnings/calendar for batch lookup of up to 50 specific tickers, and /api/earnings/date for a single ticker. Each response carries the predicted earnings and filing dates and, when available, the analyst consensus EPS estimate and expected report time.

Does the earnings calendar API include analyst EPS estimates?

Yes. All three earnings calendar API endpoints return three optional fields when they are available: epsEstimate (the analyst consensus EPS for the upcoming report), numEstimates (how many analyst estimates stand behind it), and reportTime (pre_market or after_hours). They are omitted rather than nulled for thinly covered names and for reports still weeks out. Note that epsEstimate is a Street consensus on an adjusted (operating) basis, so it will not match the GAAP diluted EPS in /api/earnings/eps-history one-for-one; use it as the market's expectation and read eps-history for the GAAP actual once the filing lands.

How do I find upcoming earnings dates programmatically?

Call /api/earnings/upcoming with days=N (1 to 28, default 7). The response is paginated and sorted by earnings date ascending; each row carries a symbols array (a multi-class issuer is one entry with all its tickers), the issuer name, the predicted earnings and filing dates, filing type, and the consensus estimate fields when available. For a watchlist of known symbols, use /api/earnings/calendar with up to 50 tickers per call. For a single symbol, use /api/earnings/date.

How does the earnings calendar API predict dates?

The earnings calendar API predicts dates from each issuer's historical SEC filing cadence (when the same-quarter 10-Q or 10-K hit EDGAR last year, plus or minus fiscal-calendar drift), cross-checked against a corporate earnings-calendar feed. For large- and mid-cap issuers the prediction lands within a few business days of the actual filing. First-time filers are excluded from /api/earnings/upcoming because there is no prior cadence to fit. For an authoritative same-day source, monitor /api/filings/latest with event=earnings.

How do I get historical EPS through the earnings API?

Call /api/earnings/eps-history with symbol, period=quarter|annual|ttm, and limit. The response contains basic EPS, diluted EPS, net income, the basic and diluted weighted-average share counts, and a pre-computed epsGrowth (year-over-year in annual mode, quarter-over-quarter in quarterly mode). Values come from income-statement XBRL in each 10-K, 10-Q, or 20-F and are split-adjusted by default.

How do I get dividend history and payout ratios from the API?

Call /api/earnings/dividend-history with symbol, period, and limit. Each period returns dividend per share, total dividends paid, payout ratio (dividends / net income), dividend coverage (operating cash flow / dividends), and year-over-year dividend growth. Non-dividend-paying companies return null values, so you can tell “never paid” apart from missing data. The endpoint is on the free tier.

What is 8-K Item 2.02 and how do I access it via API?

8-K Item 2.02 is the SEC filing section for “Results of Operations and Financial Condition,” used by US issuers to announce quarterly earnings within minutes of market close. The earnings press release is attached as Exhibit 99.1. Access it by calling /api/filings/latest with event=earnings for the market-wide stream, then /api/filings/item with item=2.02 for the body as HTML or plain text.

Which tier do I need for the earnings calendar API?

The Stock tier ($39/mo) unlocks the full earnings calendar API (/api/earnings/upcoming, /api/earnings/calendar) plus /api/earnings/trends and /api/filings/item. Starter ($15/mo) covers the single-ticker /api/earnings/date, plus /api/earnings/snapshot, /api/financials/growth, and /api/filings/latest. The free tier exposes /api/earnings/eps-history, /api/earnings/dividend-history, /api/earnings/chart/eps, and /api/earnings/chart/quality for prototyping. No credit card to sign up.

Ready to build?

Free API key, no credit card. Every endpoint mentioned in this post is available on the free tier.