# SEC XBRL Financials Scraper — Revenue, Income, Assets (`parkero/sec-financials-scraper`) Actor

Get structured financial-statement data — revenue, net income, gross profit, assets, liabilities, equity, EPS, cash flow and more — for any US public company by ticker or CIK. Full historical time series straight from the SEC official XBRL API. No API key, always current.

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

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## SEC XBRL Financials Scraper

Extract structured financial statement data from the **official SEC XBRL company facts API** — revenue, net income, assets, liabilities, cash flow, and more — for any US public company by ticker symbol or CIK number. No API key required.

### What this scraper does

This actor fetches data from the SEC's keyless XBRL company facts endpoint (`https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json`) and flattens it into a clean, one-row-per-fact dataset that downstream tools can consume without joins.

Each output record (`FinancialFact`) is fully denormalized: company name, CIK, concept label, unit, fiscal period, form type, and value are all on a single row.

### Use cases

- **Company financial statements scraper**: pull income statement, balance sheet, and cash flow data for any S\&P 500 company or small cap
- **SEC financials API**: keyless XBRL data extraction at scale
- **XBRL financial data**: standardized, machine-readable format covering hundreds of concepts
- **Revenue and net income by ticker**: track annual 10-K and quarterly 10-Q fundamentals over time
- **Fundamental analysis pipelines**: feed valuation models, stock screeners, or financial dashboards

### Input

| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `tickersOrCiks` | string\[] | Yes | — | Ticker symbols (`AAPL`, `MSFT`) or raw CIK numbers (`320193`). Mixed lists allowed. |
| `concepts` | string\[] | No | 13 defaults | XBRL concept names to extract. Absent concepts are silently skipped. |
| `taxonomy` | string | No | `us-gaap` | Taxonomy to read. Usually `us-gaap`; `dei` for entity metadata. |
| `forms` | string\[] | No | all | Only return facts from these form types (`10-K`, `10-Q`). |
| `sinceFiscalYear` | integer | No | — | Only return facts where `fy >= sinceFiscalYear`. |
| `maxPerConcept` | integer | No | — | Cap datapoints per concept per company. |
| `userAgent` | string | No | placeholder | **Required by SEC policy.** Must include a contact email. |

#### Default concepts

When `concepts` is omitted, the actor extracts these 13 fundamental financial metrics:

- `Revenues` — total revenues
- `RevenueFromContractWithCustomerExcludingAssessedTax` — ASC 606 revenues (most modern filers)
- `GrossProfit`
- `OperatingIncomeLoss`
- `NetIncomeLoss`
- `Assets`
- `Liabilities`
- `StockholdersEquity`
- `CashAndCashEquivalentsAtCarryingValue`
- `NetCashProvidedByUsedInOperatingActivities`
- `EarningsPerShareBasic`
- `EarningsPerShareDiluted`
- `ResearchAndDevelopmentExpense`

### Output

Each item in the dataset is a `FinancialFact`:

```json
{
  "company": "Apple Inc.",
  "cik": "0000320193",
  "ticker": "AAPL",
  "taxonomy": "us-gaap",
  "concept": "NetIncomeLoss",
  "label": "Net Income (Loss) Attributable to Parent",
  "unit": "USD",
  "value": 93736000000,
  "fiscalYear": 2024,
  "fiscalPeriod": "FY",
  "form": "10-K",
  "periodStart": "2023-09-25",
  "periodEnd": "2024-09-28",
  "filed": "2024-11-01",
  "frame": "CY2024"
}
```

| Field | Description |
|---|---|
| `company` | Entity name from the SEC API |
| `cik` | Zero-padded 10-digit CIK (e.g. `"0000320193"`) |
| `ticker` | Ticker symbol if resolved from input; absent for raw-CIK inputs |
| `taxonomy` | Taxonomy namespace (e.g. `us-gaap`) |
| `concept` | XBRL concept name (e.g. `NetIncomeLoss`) |
| `label` | Human-readable concept description |
| `unit` | Unit type (`USD`, `shares`, `pure`) |
| `value` | Numeric value (can be negative for losses) |
| `fiscalYear` | Fiscal year integer |
| `fiscalPeriod` | `FY`, `Q1`, `Q2`, `Q3`, or `Q4` |
| `form` | Filing form type (`10-K`, `10-Q`, etc.) |
| `periodStart` | ISO date — present for flow/income concepts; absent for balance-sheet point-in-time |
| `periodEnd` | ISO date — always present |
| `filed` | Date the filing was submitted to the SEC |
| `frame` | Standardized frame identifier (e.g. `CY2024`); present on most but not all datapoints |

### SEC fair-access policy

The SEC requires a descriptive `User-Agent` header that identifies your tool and includes a contact email. Requests without one receive HTTP 403. Set the `userAgent` input to something like `my-app/1.0 contact@example.com`. See the [SEC webmaster FAQ](https://www.sec.gov/os/webmaster-faq#developers).

### Rate limits

The SEC's documented ceiling is 10 requests/second. This actor uses a per-host rate limiter set to 120ms minimum interval (≈8.3 req/s) to stay comfortably within the limit.

### Data source

All data is fetched from the official SEC EDGAR XBRL APIs:

- Ticker→CIK map: `https://www.sec.gov/files/company_tickers.json`
- Company facts: `https://data.sec.gov/api/xbrl/companyfacts/CIK##########.json`

No third-party data providers. No API key required.

# Actor input Schema

## `tickersOrCiks` (type: `array`):

One or more ticker symbols (e.g. AAPL, MSFT) or raw SEC CIK numbers (e.g. 320193). Mixed lists are allowed — the actor resolves tickers to CIKs automatically via the official SEC ticker map.

## `concepts` (type: `array`):

XBRL concept names to extract. Omit to use the default set of 13 fundamental financial concepts (Revenues, NetIncomeLoss, Assets, Liabilities, StockholdersEquity, CashAndCashEquivalentsAtCarryingValue, NetCashProvidedByUsedInOperatingActivities, GrossProfit, OperatingIncomeLoss, EarningsPerShareBasic, EarningsPerShareDiluted, ResearchAndDevelopmentExpense, RevenueFromContractWithCustomerExcludingAssessedTax). Concepts absent for a given company are silently skipped.

## `taxonomy` (type: `string`):

Taxonomy to read from the company facts API. Defaults to 'us-gaap' (US Generally Accepted Accounting Principles). Common alternatives: 'dei' (Document Entity Information).

## `forms` (type: `array`):

Only return facts from these SEC form types. Common values: 10-K (annual report), 10-Q (quarterly report). Leave empty to return facts from all form types.

## `sinceFiscalYear` (type: `integer`):

Only return facts where the fiscal year (fy) is greater than or equal to this value. Leave blank for no lower bound. Example: 2020 returns data from fiscal year 2020 onwards.

## `maxPerConcept` (type: `integer`):

Maximum number of datapoints to return per concept per company, applied after all filters. Useful for keeping output sizes manageable when fetching many concepts for many companies. Leave blank for no cap.

## `userAgent` (type: `string`):

User-Agent string sent with every request to the SEC API. The SEC's fair-access policy REQUIRES a descriptive User-Agent that identifies your tool and includes a contact email address. Requests without a proper User-Agent are rejected with HTTP 403. Format: 'YourToolName/1.0 contact@yourdomain.com'. See https://www.sec.gov/os/webmaster-faq#developers

## Actor input object example

```json
{
  "tickersOrCiks": [
    "AAPL",
    "MSFT"
  ],
  "concepts": [
    "Revenues",
    "NetIncomeLoss",
    "Assets",
    "Liabilities",
    "StockholdersEquity"
  ],
  "taxonomy": "us-gaap",
  "forms": [
    "10-K",
    "10-Q"
  ],
  "sinceFiscalYear": 2020,
  "maxPerConcept": 20,
  "userAgent": "my-sec-financials-app/1.0 your-email@example.com"
}
```

# 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 = {
    "tickersOrCiks": [
        "AAPL",
        "MSFT"
    ],
    "concepts": [
        "Revenues",
        "NetIncomeLoss",
        "Assets",
        "Liabilities",
        "StockholdersEquity"
    ],
    "taxonomy": "us-gaap",
    "forms": [
        "10-K",
        "10-Q"
    ],
    "sinceFiscalYear": 2020,
    "maxPerConcept": 20,
    "userAgent": "my-sec-financials-app/1.0 your-email@example.com"
};

// Run the Actor and wait for it to finish
const run = await client.actor("parkero/sec-financials-scraper").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 = {
    "tickersOrCiks": [
        "AAPL",
        "MSFT",
    ],
    "concepts": [
        "Revenues",
        "NetIncomeLoss",
        "Assets",
        "Liabilities",
        "StockholdersEquity",
    ],
    "taxonomy": "us-gaap",
    "forms": [
        "10-K",
        "10-Q",
    ],
    "sinceFiscalYear": 2020,
    "maxPerConcept": 20,
    "userAgent": "my-sec-financials-app/1.0 your-email@example.com",
}

# Run the Actor and wait for it to finish
run = client.actor("parkero/sec-financials-scraper").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 '{
  "tickersOrCiks": [
    "AAPL",
    "MSFT"
  ],
  "concepts": [
    "Revenues",
    "NetIncomeLoss",
    "Assets",
    "Liabilities",
    "StockholdersEquity"
  ],
  "taxonomy": "us-gaap",
  "forms": [
    "10-K",
    "10-Q"
  ],
  "sinceFiscalYear": 2020,
  "maxPerConcept": 20,
  "userAgent": "my-sec-financials-app/1.0 your-email@example.com"
}' |
apify call parkero/sec-financials-scraper --silent --output-dataset

```

## MCP server setup

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

```

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/i1PcfJWKryEL5Vzig/builds/CQJIeem2RL7uuomIZ/openapi.json