US Company Financial Statements API: Revenue, Profit, Cash Flow

US Company Financial Statements API: Revenue, Profit, Cash Flow

Get clean annual and quarterly financial statements for US-listed companies (and foreign companies that file with the SEC, such as Novo Nordisk) as one table: revenue, profit, EPS, cash flow, balance sheet and margins. A second mode ranks all reporting companies by one metric, for example the 100 largest revenues in 2024.

The data comes from the XBRL data APIs of the U.S. Securities and Exchange Commission (SEC) (data.sec.gov, part of the SEC's EDGAR system). These are public-domain government data, published by the SEC for programmatic use without an API key or login. This Actor only reads those APIs. No browser, no proxies, no login.

What you can do with it

• Build a fundamentals table for a list of tickers: revenue, net income, EPS, free cash flow, ROE, growth
• Screen the market: "all companies with revenue above 10 billion USD in 2024, largest first"
• Feed an AI agent, spreadsheet or dashboard with reported company financials
• Compare US companies and foreign filers (IFRS, amounts in DKK, EUR, SEK ...) in one run
• Track quarterly results (Q1-Q4) for earnings analysis

Input

Mode companies (default)

Field	Description
companies	Tickers (AAPL), CIK numbers (320193) or company names (novo nordisk). A name must match exactly one company; otherwise the Actor tells you which companies match and you use the ticker instead. Up to 100 per run
periodType	annual (default) or quarterly
fromYear	Only periods ending in this year or later
maxPeriodsPerCompany	Newest periods first. Default 5 (annual) or 8 (quarterly)
contactEmail	Optional. The SEC asks automated clients to identify themselves. If you fill it in, the address is sent to the SEC in the request header, as the SEC recommends

{
    "mode": "companies",
    "companies": ["AAPL", "MSFT", "NVO"],
    "periodType": "annual",
    "maxPeriodsPerCompany": 5
}

Mode screen

Field	Description
metric	revenue, netIncome, operatingIncome, grossProfit, totalAssets, totalEquity, cash, operatingCashFlow and more (see the input form)
year, quarter	Calendar year, and 0 for the whole year or 1-4 for one quarter. Balance sheet metrics give the balance at the end of the period
maxCompanies	How many ranked companies to return (default 100)
sortOrder	desc (default) or asc
minValue	Only companies at or above this value in US dollars

{
    "mode": "screen",
    "metric": "revenue",
    "year": 2024,
    "maxCompanies": 50,
    "minValue": 10000000000
}

Output

Mode companies: one row per company and period

Field	Description
ticker, cik, companyName	Company
periodType, fiscalYear, fiscalPeriod, periodEnd	Period (FY, Q1-Q4) and its last day
currency, taxonomy	Reporting currency and accounting standard (us-gaap or ifrs-full)
form, filedDate, accession, filingUrl	The SEC filing the numbers come from
revenue, costOfRevenue, grossProfit, researchAndDevelopment, sellingGeneralAdmin, operatingIncome, netIncome	Income statement
epsBasic, epsDiluted, dilutedShares	Per share data
operatingCashFlow, investingCashFlow, financingCashFlow, capitalExpenditure, depreciationAmortization, dividendsPaid	Cash flow
totalAssets, totalLiabilities, totalEquity, cash, currentAssets, currentLiabilities, longTermDebt	Balance sheet at period end
freeCashFlow, grossMarginPct, operatingMarginPct, netMarginPct, currentRatio, returnOnEquityPct, revenueGrowthPct, netIncomeGrowthPct	Calculated by the Actor
hasDerivedValues	True if some amounts were calculated as differences (see below)
source	Attribution text

Amounts are in the reporting currency (currency), in whole units (not thousands or millions).

Mode screen: one row per ranked company

rank, ticker, cik, companyName, metric, value (US dollars), frame, periodStart, periodEnd, accession, concept, companyLocation, source.

A run also stores RUN_SUMMARY in the key-value store (rows saved, skipped inputs and why, why it stopped).

Good to know

• Source. U.S. Securities and Exchange Commission, EDGAR XBRL data, public domain. The figures are what the companies reported in their filings; the Actor does not give investment advice, and you should check important numbers against the filing (filingUrl).
• Sanity check in ranking mode. The SEC's raw data sometimes contains unit errors made by the companies themselves. The ranking therefore removes values that are implausibly large compared with the company's total assets (for example a net income of more than 2 x total assets). The number of removed values is written to the run summary (implausibleValuesRemoved). Always open the filing (accession) before you rely on a number.
• As reported. Each period uses the values from the filing for that period. If a figure is missing there, the newest filing that reports the same period is used. Later restatements of older years are therefore not always reflected.
• Quarters. Q1-Q3 come from the 10-Q reports. Cash flow figures in 10-Q reports are cumulative for the year, so the Actor subtracts the previous cumulative figure. Q4 is the full year minus the first nine months. These rows have hasDerivedValues = true. Per-share figures and share counts are not derived, so they are empty for Q4.
• Foreign companies. Companies that file annual reports on form 20-F or 40-F (for example Novo Nordisk) have annual rows only. Quarterly mode returns no rows for them.
• Empty fields. Companies tag their reports differently. If a company does not report a figure, or uses a tag the Actor does not know, the field is null. The Actor never guesses a number.
• Screen mode. Uses US GAAP data in US dollars from US-listed companies. The SEC assigns each report to the calendar period it fits best (within about 30 days), so a fiscal year ending in January 2025 is counted as 2024. A company may be missing if it reports under a different tag than the common ones.
• Tickers. Tickers come from the SEC's current ticker list. For delisted companies, use the CIK number.
• Polite access. One request per second, robots.txt is honoured, the Actor identifies itself in the User-Agent as the SEC asks, and it stops with a clear message if the SEC refuses or slows down (it does not retry with tricks). A run with 30 companies takes about half a minute.
• Cost. You pay for every row returned. Set maxPeriodsPerCompany, maxCompanies or "Maximum cost per run" to control the cost. If the cost limit is reached, the Actor stops and says so. Rows are only charged when they are saved.
• Data not included. No filing text, no insider or person data, no stock prices.
• Not affiliated. This Actor is an independent tool. It is not affiliated with, endorsed or approved by the U.S. Securities and Exchange Commission. SEC and EDGAR are registered trademarks of the SEC.