# 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use 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 '' with your token const client = new ApifyClient({ 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 '' with your token. client = ApifyClient("") # 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 " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "SEC EDGAR Financial Facts", "description": "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.", "version": "0.1", "x-build-id": "hYI5jAhLIj18G1H21" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/datamule~sec-edgar-financial-facts/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-datamule-sec-edgar-financial-facts", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/datamule~sec-edgar-financial-facts/runs": { "post": { "operationId": "runs-sync-datamule-sec-edgar-financial-facts", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/datamule~sec-edgar-financial-facts/run-sync": { "post": { "operationId": "run-sync-datamule-sec-edgar-financial-facts", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "ticker": { "title": "Ticker symbol", "type": "string", "description": "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": { "title": "CIK (Central Index Key)", "type": "string", "description": "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": { "title": "Ticker symbols (batch)", "type": "array", "description": "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.", "items": { "type": "string" } }, "ciks": { "title": "CIKs (batch)", "type": "array", "description": "Extract facts for several companies by CIK in one run, e.g. [\"320193\", \"789019\"]. Each row is tagged with its _cik.", "items": { "type": "string" } }, "concept": { "title": "Single concept (optional)", "type": "string", "description": "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": { "title": "Taxonomy (single-concept mode)", "enum": [ "us-gaap", "dei", "ifrs-full", "srt", "invest" ], "type": "string", "description": "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).", "default": "us-gaap" }, "forms": { "title": "Form filter (optional)", "type": "array", "description": "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.", "items": { "type": "string" } }, "maxRecords": { "title": "Max records (global cap)", "minimum": 1, "type": "integer", "description": "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": { "title": "User-Agent override (optional)", "type": "string", "description": "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": { "title": "Read timeout (seconds)", "minimum": 5, "type": "integer", "description": "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.", "default": 120 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```