# SEC XBRL Company Financials Extractor (`inn_corp/sec-company-financials`) Actor

Extract company financials (revenue, net income, EPS, assets, cash flow) from SEC XBRL company facts by ticker or CIK. Official SEC data, values never invented.

- **URL**: https://apify.com/inn\_corp/sec-company-financials.md
- **Developed by:** [Inn Corp](https://apify.com/inn_corp) (community)
- **Categories:** AI, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 financial facts

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?

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 Company Financials Extractor

Pull real financial figures (revenue, net income, EPS, assets, cash flow)
straight from the SEC's XBRL company facts API, by ticker or CIK. One clean
row per reported fact, with the period, unit, filing form, and accession
number attached. Built for analysts, spreadsheets, and AI agents that need
actual reported numbers instead of guesses.

### What it does

- Give it tickers (`AAPL`, `MSFT`) or CIK numbers (`0000320193`), mixed freely.
- Ask for US-GAAP concepts by exact tag (`NetIncomeLoss`, `Assets`,
  `EarningsPerShareDiluted`), or leave the list empty for a default set of
  ten common income-statement, balance-sheet, and cash-flow concepts.
- The special alias `revenue` handles the fact that companies tag revenue
  under different concepts: it tries
  `RevenueFromContractWithCustomerExcludingAssessedTax`, then `Revenues`,
  then `SalesRevenueNet`, uses the first tag that has any facts, and reports
  which one matched in the `matchedTag` field of every row. No silent merging.
- Filter to annual facts, quarterly facts, or both, and to a fiscal-year range.
- Restatement handling: the same period is re-reported in later filings as a
  comparative. By default the Actor keeps only the most recently filed value
  per concept, unit, and period (`dedupe: true`); turn it off to see every
  reported instance.

### What it deliberately does not do

- **No invented numbers.** Every value comes from the SEC's XBRL payload.
  Missing data is `null`, never estimated or filled in by a model.
- **No derived ratios.** You get the reported facts; margins, growth rates,
  and multiples are your job (or your model's), with the inputs cited.
- **No IFRS foreign filers in v1.** The Actor reads the `us-gaap` taxonomy.
  Companies that file only under IFRS are skipped with a clear warning.

### Data source and compliance

All data comes from the U.S. Securities and Exchange Commission's official
XBRL company facts endpoint, which is public domain. The SEC permits scripted
access with a declared User-Agent and a rate under 10 requests/second; this
Actor declares its User-Agent (with the contact email you provide) and stays
well under that limit with built-in throttling and retries. The dataset
contains company-level financials only; no personal data.

### Output example

Real output row (Apple's fiscal 2024 revenue, as reported in the FY2025 10-K):

```json
{
  "ticker": "AAPL",
  "cik": "0000320193",
  "entityName": "Apple Inc.",
  "concept": "revenue",
  "matchedTag": "RevenueFromContractWithCustomerExcludingAssessedTax",
  "label": "Revenue from Contract with Customer, Excluding Assessed Tax",
  "unit": "USD",
  "value": 391035000000,
  "periodStart": "2023-10-01",
  "periodEnd": "2024-09-28",
  "fy": 2025,
  "fp": "FY",
  "form": "10-K",
  "filed": "2025-10-31",
  "accession": "0000320193-25-000079",
  "frame": "CY2024"
}
```

Note the `fy`/`fp` fields describe the filing that reported the fact, exactly
as the SEC tags them: the fiscal-2024 period above was most recently reported
in the fiscal-2025 10-K, so `fy` is 2025. Because `fy` is the filing's year,
`fromYear: 2020` can still return periods before 2020; filter on `periodEnd`
if you need the period's own year. The period itself is always
`periodStart`/`periodEnd` (instantaneous facts like `Assets` have a null
`periodStart`). Per-share concepts come back in `USD/shares`, share counts in
`shares`.

### Typical uses

- Feed an AI agent (via MCP or the API) real reported financials so its
  analysis cites periods, forms, and accession numbers.
- Pull ten years of annual fundamentals for a watchlist into a spreadsheet.
- Track quarterly net income across companies without touching a filing PDF.
- Build datasets of as-reported (or latest-restated) figures for research.

### Input

| Field | Meaning |
| --- | --- |
| `companies` | Tickers or CIKs, mixed. Required. |
| `concepts` | US-GAAP tags, plus the `revenue` alias. Empty = default set of ten. |
| `periodType` | `annual` (fiscal-year facts only), `quarterly` (Q1-Q4 facts), or `both`. |
| `fromYear` / `toYear` | Fiscal-year window, applied to the SEC's `fy` field. |
| `dedupe` | Keep only the latest-filed value per concept, unit, and period. Default on. |
| `maxRowsPerCompany` | Newest period first, default 500. When the cap bites, it is shared across the requested concepts (round-robin, remainder to the concepts listed first), so a low cap trims every concept evenly instead of silently dropping the ones listed last. Trims are logged per concept. |
| `contactEmail` | Used only inside the SEC User-Agent header and sent only to sec.gov. Never written to the output dataset or the logs. (Like any Actor input, the Apify platform keeps it in your run's input record.) |

Annual note: older filings tag quarterly comparative facts `fp: "FY"` inside
10-Ks, so annual mode additionally requires duration facts to span at least
340 days (a full 52- or 53-week fiscal year). Instantaneous facts like
`Assets` are point-in-time and are kept by the FY/10-K rule alone.

Quarterly note: the SEC tags year-to-date durations with the same `fp` as the
quarter they end in, and fourth quarters usually appear only inside the annual
(FY) facts. Both behaviors are the SEC's own tagging, passed through honestly;
use `periodStart`/`periodEnd` to tell a three-month fact from a year-to-date
one.

### Fair pricing

Pay per financial fact returned once pay-per-event pricing is enabled, plus a
small per-company charge for each company processed. No subscription.

# Actor input Schema

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

Company tickers (AAPL, MSFT) or CIK numbers (0000320193). Mix freely.

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

US-GAAP XBRL tags (NetIncomeLoss, Assets) or the alias "revenue", which tries RevenueFromContractWithCustomerExcludingAssessedTax, then Revenues, then SalesRevenueNet, and reports which tag matched. Leave empty for a default set of ten common concepts.

## `periodType` (type: `string`):

Annual keeps fiscal-year facts (fp = FY or 10-K rows) and requires duration facts to span at least 340 days, so quarterly comparatives tagged FY in older 10-Ks are excluded. Quarterly keeps Q1-Q4 facts. Both keeps everything.

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

Keep facts with fiscal year >= this. Leave empty for no lower bound.

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

Keep facts with fiscal year <= this. Leave empty for no upper bound.

## `dedupe` (type: `boolean`):

The same period is often re-reported in later filings. When on, keep only the most recently filed value per concept, unit, and period.

## `maxRowsPerCompany` (type: `integer`):

Newest period first.

## `contactEmail` (type: `string`):

The SEC requires a contact email in the User-Agent header. It is sent only to sec.gov and never written to the output or logs.

## Actor input object example

```json
{
  "companies": [
    "AAPL",
    "MSFT",
    "0000320193"
  ],
  "concepts": [
    "revenue",
    "NetIncomeLoss",
    "EarningsPerShareDiluted"
  ],
  "periodType": "annual",
  "dedupe": true,
  "maxRowsPerCompany": 500,
  "contactEmail": "you@example.com"
}
```

# Actor output Schema

## `facts` (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 = {
    "companies": [
        "AAPL"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("inn_corp/sec-company-financials").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 = { "companies": ["AAPL"] }

# Run the Actor and wait for it to finish
run = client.actor("inn_corp/sec-company-financials").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 '{
  "companies": [
    "AAPL"
  ]
}' |
apify call inn_corp/sec-company-financials --silent --output-dataset

```

## MCP server setup

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

```

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/v1sCeFMZ1n9yjYpog/builds/cCyROJmqRe2eEDBPC/openapi.json