# SEC EDGAR Financial Facts (`datamule/sec-edgar-financial-facts`) Actor

Give a ticker or CIK, get every reported XBRL financial fact for any US public company from the official SEC EDGAR company-facts API (data.sec.gov) — revenue, assets, EPS, cash, liabilities and every us-gaap + dei concept, flattened to one analysis-ready row per observation. No API key.

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

## Pricing

from $0.35 / 1,000 facts

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## 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 EDGAR Financial Facts

Give a **ticker or CIK**, get **every reported XBRL financial fact** for any U.S. public
company — straight from the **official SEC EDGAR company-facts REST API**
(`data.sec.gov`). Revenue, assets, EPS, cash, liabilities, shares outstanding — every
`us-gaap` and `dei` concept the filer has tagged — flattened to **one analysis-ready row
per reported fact-observation**. Free, no API key, authoritative source.

SEC EDGAR is *the* system of record for U.S. public-company financials. This actor is the
clean **structured-fundamentals** extractor built directly on the official XBRL API —
normalized, analysis-ready numbers, not raw filing HTML you have to parse yourself.

### What you get

One dataset row per fact-observation, with these fields:

| Field | Meaning |
|-------|---------|
| `cik` | Central Index Key (integer) |
| `entityName` | Company name, e.g. `Apple Inc.` |
| `taxonomy` | `us-gaap` | `dei` | `ifrs-full` | `srt` | `invest` |
| `concept` | The XBRL tag, e.g. `Revenues`, `Assets`, `EarningsPerShareBasic` |
| `label` | Human label for the concept |
| `description` | The concept's full XBRL definition |
| `unit` | `USD`, `shares`, `USD/shares`, … |
| `value` | The reported number (int for money/shares, float for per-share) |
| `start` | Period start (**null** for *instant* facts like a balance-sheet total) |
| `end` | Period end (or the instant date) |
| `fiscalYear` | Fiscal year (`fy`) |
| `fiscalPeriod` | Fiscal period (`fp`) — `FY`, `Q1`, `Q2`, … |
| `form` | SEC form, e.g. `10-K`, `10-Q`, `8-K` |
| `filed` | Filing date |
| `accessionNumber` | The filing's accession number (`accn`) |
| `frame` | The XBRL frame if present (e.g. `CY2016`, `CY2009Q2I`), else null |
| `_cik` | The zero-padded CIK this row was fetched under |
| `_source` | `companyconcept` (single concept) or `companyfacts` (all concepts) |
| `_rowIndex` | Sequential index within the run |
| `_raw` | The lossless original observation object |

### Input

| Input | Description |
|-------|-------------|
| `ticker` | A stock ticker, e.g. `AAPL` — resolved to a CIK via SEC's official ticker map |
| `cik` | A Central Index Key, e.g. `320193` (zero-padding handled for you) |
| `tickers` / `ciks` | Batch several companies in one run; each row is tagged with its `_cik` |
| `concept` | A single concept tag (e.g. `Revenues`) → uses the fast per-concept endpoint. Omit to extract **all** concepts |
| `taxonomy` | Taxonomy for the concept (default `us-gaap`); only used with `concept` |
| `forms` | Keep only these SEC form types, e.g. `["10-K","10-Q"]` |
| `maxRecords` | Global cap on rows emitted (a large filer's full fact set can be tens of thousands) |
| `userAgent` | Optional override — a compliant default is sent (SEC requires a descriptive UA) |
| `timeoutSecs` | Per-request read timeout (default 120s) |

At least one identifier (`cik`/`ticker`/`ciks`/`tickers`) is required.

#### Example — one concept for one company

```json
{ "cik": "320193", "concept": "Revenues", "taxonomy": "us-gaap" }
```

#### Example — full fundamentals for a company (capped)

```json
{ "ticker": "AAPL", "maxRecords": 500 }
```

#### Example — annual EPS across several companies

```json
{ "tickers": ["AAPL", "MSFT", "GOOGL"], "concept": "EarningsPerShareBasic", "forms": ["10-K"] }
```

### How it works

- Two official endpoints, auto-selected: **`companyconcept`** (one concept for one
  company) when you set `concept`, otherwise **`companyfacts`** (every concept the filer
  tagged). Ticker → CIK resolution uses SEC's official `company_tickers.json` directory.
- **The parse is the moat.** The XBRL facts JSON is deeply nested
  (`facts.{taxonomy}.{concept}.units.{unit}[]`) and every observation is flattened fully.
  Every field is read by **key presence**, so an *instant* fact (no `start`) or a fact
  with no `frame` yields `null` there — never a dropped row, never a crash. The complete
  original observation is preserved in `_raw`.
- **SEC fair-access compliant.** SEC requires a descriptive `User-Agent` with contact
  info (it returns HTTP 403 otherwise) and asks clients to stay ≤ ~10 requests/second.
  The actor sends a compliant UA by default and throttles between requests.
- **Honest and resilient.** An unknown CIK/ticker, a concept a company never tagged, a
  timeout, or a non-JSON body is a clean skip-with-warning and the batch continues; a run
  where *every* identifier is skipped fails fast so nothing broken looks successful. A
  valid company with no facts for your filter returns 0 rows — it never fabricates data.

### Pricing

Pay-per-event: you're charged per **fact** (one emitted dataset row).

### Notes

Data comes directly from SEC EDGAR's XBRL frames API and is provided as-is from the
filers' own submissions. This actor accesses only public, no-auth SEC endpoints.

# Actor input Schema

## `ticker` (type: `string`):

A U.S. stock ticker to look up, e.g. "AAPL", "MSFT", "NVDA". It is resolved to the company's Central Index Key (CIK) via SEC's official ticker directory (https://www.sec.gov/files/company\_tickers.json). Provide a ticker OR a CIK (or use the batch arrays below) — at least one identifier is required.

## `cik` (type: `string`):

A company's SEC Central Index Key, e.g. "320193" for Apple. Zero-padding is handled for you (320193 becomes CIK0000320193). Provide a CIK OR a ticker. Use this when you already know the CIK — it skips the ticker lookup.

## `tickers` (type: `array`):

Look up several companies by ticker in one run, e.g. \["AAPL", "MSFT", "GOOGL"]. Each emitted row is tagged with the CIK it came from (\_cik). Combine freely with the CIK batch below.

## `ciks` (type: `array`):

Extract facts for several companies by CIK in one run, e.g. \["320193", "789019"]. Each row is tagged with its \_cik.

## `concept` (type: `string`):

Restrict to ONE XBRL concept tag, e.g. "Revenues", "Assets", "EarningsPerShareBasic", "NetIncomeLoss", "CashAndCashEquivalentsAtCarryingValue". When set, the fast per-concept companyconcept endpoint is used (one concept for the company). Leave empty to extract EVERY reported concept (us-gaap + dei) via the full companyfacts endpoint — the complete fundamentals set. The tag is case-sensitive and must match the XBRL element name.

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

The XBRL taxonomy the concept belongs to. Only used when "concept" is set. us-gaap (US GAAP financial concepts — the default, covers revenues/assets/EPS/etc.), dei (Document & Entity Information — shares outstanding, public float), ifrs-full (IFRS filers), srt (SEC reporting taxonomy), invest (investment schedules).

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

Keep only fact-observations reported on these SEC form types, e.g. \["10-K"] for annual only, or \["10-K", "10-Q"] for annual + quarterly. Other common values: 8-K, 20-F, 40-F, S-1. Leave empty to keep facts from every form the filer used.

## `maxRecords` (type: `integer`):

A GLOBAL cap on the number of fact rows to emit across ALL companies (each row is one fact-observation and one billable event). A full companyfacts run on a large filer can return tens of thousands of facts, so a cap makes a cheap, deterministic sample. Leave empty to extract every matching fact.

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

SEC's fair-access policy REQUIRES every automated request to send a descriptive User-Agent that includes contact info, or it returns HTTP 403. The actor already sends a compliant default, so you normally leave this empty. Override it only if you want SEC to see your own contact string, e.g. "MyCompany research (contact@example.com)". A blank or generic UA will be rejected by SEC.

## `timeoutSecs` (type: `integer`):

Per-request read timeout. The full companyfacts document for a large filer is several megabytes, so the default is generous. Increase it if you extract many large filers in one run.

## Actor input object example

```json
{
  "ticker": "AAPL",
  "taxonomy": "us-gaap",
  "maxRecords": 500,
  "timeoutSecs": 120
}
```

# 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 = {
    "ticker": "AAPL",
    "maxRecords": 500
};

// Run the Actor and wait for it to finish
const run = await client.actor("datamule/sec-edgar-financial-facts").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 = {
    "ticker": "AAPL",
    "maxRecords": 500,
}

# Run the Actor and wait for it to finish
run = client.actor("datamule/sec-edgar-financial-facts").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "ticker": "AAPL",
  "maxRecords": 500
}' |
apify call datamule/sec-edgar-financial-facts --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=datamule/sec-edgar-financial-facts",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/38pWkaCedS5sQcl5z/builds/hYI5jAhLIj18G1H21/openapi.json