# SEC XBRL Fundamentals: Financial Statements API & Screener (`cprussin/sec-xbrl-fundamentals`) Actor

Official SEC XBRL financials for any US-listed company: revenue, margins, EPS, balance sheet, cash flow and FCF per year, quarter (derived Q4) or TTM, each value traced to its filing. Plus a screener across every filer. $3 per 1,000 periods.

- **URL**: https://apify.com/cprussin/sec-xbrl-fundamentals.md
- **Developed by:** [Connor Prussin](https://apify.com/cprussin) (community)
- **Categories:** Business, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 company periods

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## SEC XBRL Fundamentals: financial statements API and screener for every US public company

**SEC XBRL Fundamentals** returns clean, normalized **financial statements** for any company that files with the SEC, read from the official XBRL data on `data.sec.gov`. You get one row per company and period (fiscal year, quarter or trailing twelve months) with about 35 metrics: revenue, gross profit, operating income, net income, EPS, cash, debt, assets, equity, operating cash flow, capex, free cash flow and more. Every value carries its **source**: the XBRL tag, the accession number, the form and the filing date.

A second **screener** mode lists one metric for **every SEC filer** in a calendar period, for example all companies with more than $1B of revenue in 2024, filtered by value and state.

- ✅ **Official as-filed numbers** from SEC XBRL filings (10-K, 10-Q). No login, proxy or API key needed.
- ✅ **One clean schema** for every company: synonym tags (`Revenues`, `RevenueFromContractWithCustomerExcludingAssessedTax`, `SalesRevenueNet`…) are merged into one `revenue` column.
- ✅ **Annual, quarterly and TTM**: Q4 is derived from the 10-K (FY minus nine months), cash-flow quarters from year-to-date statements, TTM from the last four quarters.
- ✅ **Traceable**: `sources` names the tag, filing and method behind each number.
- ✅ **Screener** across every XBRL filer: one metric, one period, min/max and state filters.
- ✅ Look companies up by **ticker, CIK or name**.

### Start in one minute

Click **Start** with the prefilled input:

```json
{
  "mode": "company",
  "companies": ["AAPL", "MSFT"],
  "periodTypes": ["annual"],
  "fromYear": 2022,
  "maxItems": 10
}
```

You get: Apple's and Microsoft's fiscal years from 2022 on, newest first, with `revenue`, `netIncome`, `epsDiluted`, `freeCashFlow` and the rest.

**Cost:** up to $0.03: 10 periods × $0.003, plus the $0.00005 actor-start fee.

### Use with an AI assistant

Connect the [Apify MCP server](https://mcp.apify.com) to Claude, ChatGPT, Cursor or any MCP client (`https://mcp.apify.com?tools=cprussin/sec-xbrl-fundamentals` loads only this actor), then paste:

```text
Use the Apify actor cprussin/sec-xbrl-fundamentals to get quarterly and TTM financials for NVDA and AMD since fiscal 2024, then compare their revenue growth, gross margin and free cash flow.
```

### Recipes

#### Quarterly financials with derived Q4

```json
{
  "companies": ["NVDA"],
  "periodTypes": ["quarterly"],
  "fromYear": 2024,
  "maxItems": 20
}
```

#### TTM snapshot for a watchlist

Trailing-twelve-month revenue, earnings and cash flow at each quarter end; keep the newest per company.

```json
{
  "companies": ["AAPL", "Coca-Cola Co", "789019"],
  "periodTypes": ["ttm"],
  "fromYear": 2026,
  "maxItems": 30
}
```

#### Screener: every company with $1B+ revenue in 2024

```json
{
  "mode": "screener",
  "metric": "revenue",
  "period": "CY2024",
  "minValue": "1000000000",
  "maxItems": 5000
}
```

#### Screener: California companies by total assets

Balance-sheet metrics are point-in-time: `CY2024` becomes `CY2024Q4I` (the 2024 year end).

```json
{
  "mode": "screener",
  "metric": "totalAssets",
  "period": "CY2024",
  "states": ["CA"],
  "maxItems": 100
}
```

#### Screener: any us-gaap tag

```json
{
  "mode": "screener",
  "customTag": "Goodwill",
  "customUnit": "USD",
  "period": "CY2025Q2I",
  "maxItems": 100
}
```

### Who uses SEC fundamentals?

- **Investors and analysts** pull standardized statements and TTM figures without Yahoo or paid terminals.
- **Quants and data scientists** build factor datasets and backtests from as-filed numbers with filing dates (no look-ahead).
- **Fintech and AI agents** feed company financials into apps, dashboards and LLM answers with a citation for every number.
- **Researchers and journalists** rank whole industries with the screener.

### How does it work?

1. **Company mode:** each ticker or name is resolved to its SEC CIK (via `company_tickers.json`), then the company's XBRL facts are read from `data.sec.gov/api/xbrl/companyfacts`.
2. Periods come from the company's 10-K and 10-Q filings. For each metric, the first tag in its fallback list that has a value wins.
3. Quarters missing from the filings are derived: Q4 = full year − nine months (or − Q1−Q3), Q2/Q3 cash flow = year-to-date − previous year-to-date. TTM sums the last four quarters; at a fiscal year end it equals the annual figure.
4. **Screener mode:** the SEC's `frames` API returns one value per filer for a tag and calendar period. All synonym tags of the metric are queried and merged (one row per company), then filtered and sorted.

The actor follows the [SEC's fair-access policy](https://www.sec.gov/os/accessing-edgar-data): it sends a declared User-Agent, stays under 10 requests per second (3 in parallel) and backs off on HTTP 429/503.

### Input

| Field                     | Mode     | Description                                                             | Example              |
| ------------------------- | -------- | ----------------------------------------------------------------------- | -------------------- |
| `mode`                    | both     | `company` or `screener`                                                 | `"company"`          |
| `companies`               | company  | Tickers, CIKs or registered names                                       | `["AAPL", "320193"]` |
| `periodTypes`             | company  | `annual`, `quarterly`, `ttm` (default `annual`)                         | `["annual", "ttm"]`  |
| `fromYear` / `toYear`     | company  | Fiscal-year range (empty = everything SEC has, from about 2009)         | `2022`               |
| `metric`                  | screener | Metric key (see the output fields), default `revenue`                   | `"netIncome"`        |
| `period`                  | screener | `CY2024`, `CY2024Q2` or `CY2024Q4I` (instant); default last year        | `"CY2024"`           |
| `minValue` / `maxValue`   | screener | Value range, as text                                                    | `"1000000000"`       |
| `states`                  | screener | US business-address states (excludes non-US filers when set)            | `["CA", "NY"]`       |
| `sortBy`                  | screener | `valueDesc`, `valueAsc` or `name`                                       | `"valueDesc"`        |
| `customTag`, `customUnit` | screener | Any us-gaap tag instead of a metric; unit USD, USD/shares, shares, pure | `"Goodwill"`         |
| `maxItems`                | both     | Maximum records (each is billed)                                        | `100`                |

### What data do you get?

**Company mode**, one item per company and period (shortened):

```json
{
  "recordType": "company-period",
  "cik": "320193",
  "ticker": "AAPL",
  "companyName": "Apple Inc.",
  "periodType": "quarterly",
  "fiscalYear": 2026,
  "fiscalPeriod": "Q4",
  "periodStart": "2026-06-28",
  "periodEnd": "2026-09-26",
  "form": "10-K",
  "accessionNumber": "0000320193-26-000026",
  "filed": "2026-11-03",
  "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000026/0000320193-26-000026-index.htm",
  "currency": "USD",
  "revenue": 114477000000,
  "costOfRevenue": 59657000000,
  "grossProfit": 54820000000,
  "operatingIncome": 35631000000,
  "netIncome": 30711000000,
  "epsDiluted": 2.11,
  "cash": 36305000000,
  "totalAssets": 404548000000,
  "totalLiabilities": 292455000000,
  "stockholdersEquity": 112093000000,
  "totalDebt": 80111000000,
  "sharesOutstanding": 14532259000,
  "operatingCashFlow": 28101000000,
  "capitalExpenditures": 2242000000,
  "freeCashFlow": 25859000000,
  "sources": {
    "revenue": {
      "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
      "accn": "0000320193-26-000026",
      "form": "10-K",
      "filed": "2026-11-03",
      "method": "ytd-difference",
      "accns": ["0000320193-26-000020", "0000320193-26-000026"]
    }
  }
}
```

**All metrics:** `revenue`, `costOfRevenue`, `grossProfit`, `researchAndDevelopment`, `sellingGeneralAdministrative`, `operatingExpenses`, `operatingIncome`, `interestExpense`, `pretaxIncome`, `incomeTaxExpense`, `netIncome`, `epsBasic`, `epsDiluted`, `weightedSharesBasic`, `weightedSharesDiluted`, `dividendsPerShare`, `cash`, `shortTermInvestments`, `accountsReceivable`, `inventory`, `currentAssets`, `totalAssets`, `currentLiabilities`, `totalLiabilities`, `stockholdersEquity`, `shortTermDebt`, `longTermDebt`, `totalDebt`, `sharesOutstanding`, `operatingCashFlow`, `capitalExpenditures`, `freeCashFlow`, `depreciationAmortization`, `stockBasedCompensation`, `dividendsPaid`, `shareRepurchases`. A metric the company doesn't report is `null`.

**Screener mode**, one item per filer:

```json
{
  "recordType": "frame-row",
  "cik": "320193",
  "ticker": "AAPL",
  "companyName": "Apple Inc.",
  "metric": "revenue",
  "value": 391035000000,
  "unit": "USD",
  "period": "CY2024",
  "periodStart": "2023-10-01",
  "periodEnd": "2024-09-28",
  "state": "CA",
  "country": "US",
  "location": "US-CA",
  "accessionNumber": "0000320193-26-000026",
  "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000026/0000320193-26-000026-index.htm",
  "sources": {
    "value": {
      "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
      "accn": "0000320193-26-000026"
    }
  }
}
```

**Field notes**

- `sources.*.method`: `reported` (one fact as filed), `ytd-difference` (year-to-date minus the previous year-to-date), `fy-minus-quarters` (FY − Q1 − Q2 − Q3), `ttm-sum` (four quarters), `approximate` (per-share Q4/TTM by subtraction or summing) or `computed` (e.g. free cash flow = operating cash flow − capex; total debt = short-term + long-term debt).
- Amounts are **as first reported**; per-share values and share counts use the **latest** filing, so stock splits are reflected where a later filing restated them.
- Weighted-average share counts are never derived (null for derived Q4 and TTM).
- `fiscalYear` is the company's own fiscal year label (e.g. Apple's FY2026 ends in September 2026).
- Screener `period` is the SEC calendar frame: the SEC maps each company's fiscal period to the nearest calendar year or quarter.
- Only `us-gaap` USD facts are used, so most foreign private issuers (IFRS) are not covered.

### How much does it cost?

This actor is priced **per result** (pay-per-event):

| Event                                                   | Price      |
| ------------------------------------------------------- | ---------- |
| Company period (one company × one year, quarter or TTM) | **$0.003** |
| Screener row (one filer's value)                        | **$0.001** |

For example, ten years of annual data for 100 companies (1,000 periods) costs $3.00; a screen of 5,000 filers costs $5.00. Periods with almost no data are skipped and not billed. If you set a **maximum cost per run**, the actor stops cleanly at that limit.

### Tips

- Combine `periodTypes: ["quarterly", "ttm"]` for both views in one run.
- Use `filed` and `accessionNumber` to build point-in-time datasets without look-ahead bias.
- To identify your own organization to the SEC, set a `SEC_USER_AGENT` environment variable (your company name and a contact email address).
- Send results to Google Sheets, Slack, email or a webhook through Apify integrations.

### FAQ

**Is this data official?** Yes. Every value comes from SEC XBRL data, and `filingUrl` links to the original filing.

**How fresh is it?** The SEC updates its XBRL APIs within minutes of a filing being accepted.

**Why is a metric null?** The company doesn't report a matching tag for that period (banks have no gross profit, many companies combine SG\&A lines), or a quarter couldn't be derived.

**Disclaimer:** This actor is not affiliated with the U.S. Securities and Exchange Commission, and its output is not investment advice.

### Related actors

- [SEC Form D Funding](https://apify.com/cprussin/sec-form-d-funding?fpr=to54nm): New SEC Form D filings: startup funding rounds and private placements.
- [Federal Recompete Radar](https://apify.com/cprussin/federal-recompete-radar?fpr=to54nm): US federal contracts nearing expiry, with incumbent and value, for recompete pipelines.

# Actor input Schema

## `mode` (type: `string`):

<b>Company</b>: normalized financial statements (about 35 metrics) for each company and fiscal year, quarter or TTM period. <b>Screener</b>: one metric for every SEC filer in one calendar period, with value and state filters.

## `companies` (type: `array`):

Company mode: stock tickers (AAPL, BRK-B), SEC CIK numbers (320193) or registered company names (Apple Inc.).

## `periodTypes` (type: `array`):

Annual (fiscal years from 10-K), quarterly (Q1-Q4; Q4 and cash-flow quarters derived from year-to-date figures) and/or TTM (trailing twelve months at each quarter end).

## `fromYear` (type: `integer`):

Only periods in this fiscal year or later. Empty = all years SEC has (XBRL data starts 2009-2011).

## `toYear` (type: `integer`):

Only periods up to this fiscal year. Empty = latest.

## `metric` (type: `string`):

Screener mode: the metric to list for every filer. All synonym XBRL tags are queried and merged (one row per company).

## `period` (type: `string`):

Screener mode: CY2024 (calendar year), CY2024Q2 (calendar quarter) or CY2024Q4I (balance sheet at the quarter end). Fiscal years are aligned to the nearest calendar period by the SEC. Empty = last calendar year.

## `minValue` (type: `string`):

Screener mode: only filers with a value at or above this, e.g. 1000000000 for $1B revenue or 2.5 for EPS.

## `maxValue` (type: `string`):

Screener mode: only filers with a value at or below this.

## `states` (type: `array`):

Screener mode: only filers whose business address is in these US states (two-letter codes such as CA, NY). Empty = every filer, including non-US.

## `sortBy` (type: `string`):

Screener mode: order of the rows (and which ones are kept when 'Max results' cuts the list).

## `customTag` (type: `string`):

Screener mode, advanced: any us-gaap XBRL tag (e.g. Goodwill, AdvertisingExpense) instead of a metric. Use a period ending in I (CY2024Q4I) for balance-sheet tags.

## `customUnit` (type: `string`):

Unit of the custom tag: USD, USD/shares, shares or pure.

## `maxItems` (type: `integer`):

Maximum records to return: company periods in company mode, filers in screener mode. Each record is billed as one event.

## Actor input object example

```json
{
  "mode": "company",
  "companies": [
    "AAPL",
    "MSFT"
  ],
  "periodTypes": [
    "annual"
  ],
  "fromYear": 2022,
  "metric": "revenue",
  "sortBy": "valueDesc",
  "customUnit": "USD",
  "maxItems": 10
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "company",
    "companies": [
        "AAPL",
        "MSFT"
    ],
    "periodTypes": [
        "annual"
    ],
    "fromYear": 2022,
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("cprussin/sec-xbrl-fundamentals").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "company",
    "companies": [
        "AAPL",
        "MSFT",
    ],
    "periodTypes": ["annual"],
    "fromYear": 2022,
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("cprussin/sec-xbrl-fundamentals").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "company",
  "companies": [
    "AAPL",
    "MSFT"
  ],
  "periodTypes": [
    "annual"
  ],
  "fromYear": 2022,
  "maxItems": 10
}' |
apify call cprussin/sec-xbrl-fundamentals --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,cprussin/sec-xbrl-fundamentals"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/gFaTrsayI7nDPzMGy/builds/QsB9oQhl2ZfbDjmxW/openapi.json