# SEC XBRL Screener - Company Financials Data (`dataio/sec-edgar-xbrl-financial-screener`) Actor

Screen US public companies on SEC XBRL financial data: pick metrics and a period, get one row per company with a column for each, such as revenue, net income, assets, cash and R\&D, joined across thousands of SEC EDGAR filers. Sort like a stock screener. No API key.

- **URL**: https://apify.com/dataio/sec-edgar-xbrl-financial-screener.md
- **Developed by:** [Tom Awake](https://apify.com/dataio) (community)
- **Categories:** MCP servers
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 company rows

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/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

### What does SEC XBRL Screener do?

Pick financial metrics and a period. Get **one row per US public company,
one column per metric** — joined across thousands of SEC filers.

**No login. No API key. No proxies.**

### What the raw SEC API makes you do

The SEC's XBRL frames API returns **one metric at a time**. One call gives
you revenue for 1,934 companies. Another gives you total assets for 5,650.
Joining them, and knowing they are not even asked for the same way, is left
to you.

This Actor does the joining. Three metrics, three calls, one table:

| Company | Revenue | Net income | Assets |
|---|---|---|---|
| WALMART INC. | 165.6 B | 4.5 B | 262.4 B |
| UnitedHealth Group | 109.6 B | 6.3 B | 309.8 B |
| CVS HEALTH | 94.6 B | 1.8 B | 255.6 B |

### Two traps it handles that cost you data

**Duration versus instant.** Revenue happens *over* a quarter; assets exist
*at* a date. The SEC encodes that as `CY2025Q1` against `CY2025Q1I`, and
asking the wrong way returns a bare 404 with no explanation. Balance-sheet
metrics are marked in the picker and the period is adjusted for you.

**There is no single revenue concept.** Companies reporting under ASC 606
tag `RevenueFromContractWithCustomerExcludingAssessedTax` and never populate
`Revenues`. Query only the obvious one and you silently lose the largest
companies in the market:

| Metric used | Coverage on $1B+ R\&D companies |
|---|---|
| `us-gaap:Revenues` alone | **41 %** — no Apple, no Meta, no Microsoft |
| **Revenue (any reported basis)** | **100 %** |

The default revenue metric queries all three concepts and keeps the first
value each company actually reported. Every row carries a
`revenue_concept` column naming which one it came from, so you can see when
you are comparing unlike bases.

### Output

Stable columns: `cik`, `entityName`, `location`, `secUrl`.

Then per metric: the value, plus `_periodEnd` (the date the figure covers),
`_accession` (the filing it came from) and `_concept` (the us-gaap tag used).
Every row carries every requested column, empty where not reported, so the
file stays rectangular for a spreadsheet.

### Metrics

**Income statement** — revenue (any basis), revenue (strict), revenue from
contracts, gross profit, operating income, net income, R\&D expense, SG\&A
expense, interest expense, EPS diluted, EPS basic

**Cash flow** — operating cash flow, capital expenditure

**Balance sheet** — total assets, total liabilities, stockholders' equity,
cash and equivalents, long-term debt, inventory, goodwill, shares
outstanding

### Input

```json
{
  "metrics": ["revenue", "net-income", "assets"],
  "year": 2025,
  "quarter": "Q1",
  "maxItems": 2000
}
```

| Field | Default | Notes |
|---|---|---|
| `metrics` | revenue, net income, assets | One column each; each costs a call |
| `year` | `2025` | XBRL starts around 2009 |
| `quarter` | `Q1` | Q1–Q4 or full year |
| `onlyComplete` | `false` | Keep only companies reporting every metric |
| `maxItems` | `2000` | Rows, sorted by the sort metric |
| `sortBy` | first metric | Must be one you selected |
| `minValue` | — | Threshold on the sort metric |

### Use cases

- **Screening** — every company above a revenue, R\&D or debt threshold.
- **Peer benchmarking** — pull a peer set and compare on identical metrics.
- **Market and sector sizing** — aggregate a metric across all filers.
- **Model inputs** — a clean quarterly panel without a data vendor.
- **Anomaly hunting** — companies whose reported figures move oddly between
  quarters.

### Limits, honestly

- **Recent quarters fill in over months.** Companies file on their own
  schedules, so the latest quarter is always partial. Step back a quarter
  for a complete picture.
- **Coverage differs per metric.** Net income is tagged by 5,361 companies,
  revenue by fewer, long-term debt by 1,534. A missing value usually means
  the company did not tag that concept, not that the figure is zero.
- **Fiscal years are not calendar years.** A frame labelled CY2025Q1 groups
  what companies reported as that calendar period; a company with a January
  year-end aligns differently. `_periodEnd` on every row tells you exactly
  what was covered.
- `onlyComplete` can cut results sharply — one untagged concept removes the
  company entirely.
- Requests are paced and carry an identifying User-Agent, as the SEC
  requires.
- Not affiliated with the SEC.

### Use SEC XBRL Screener as an API

Call it from your own code with the Apify client, here in Python:

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_APIFY_TOKEN>")
run = client.actor("DataIO/sec-edgar-xbrl-financial-screener").call(run_input={
    'metrics': ['revenue', 'net-income', 'assets'],
    'year': 2025,
    'quarter': 'Q1',
    'maxItems': 500,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

It also works from JavaScript, Make, Zapier, n8n, and from AI agents through the Apify MCP server.

### Other actors you might like

- [GLEIF LEI Lookup](https://apify.com/DataIO/gleif-lei-lookup): Legal Entity Identifier API
- [BODACC Scraper](https://apify.com/DataIO/bodacc-french-insolvencies-sales): French Insolvencies & Sales
- [IRS 990 Scraper](https://apify.com/DataIO/irs-990-nonprofit-financials): Nonprofit Financials & Revenue

### FAQ

#### Is it legal to use this data?

The actor reads public data from its official source, without logging in and without bypassing any access control. What you do with the data, for example contacting people listed in it, is your responsibility under the laws that apply to you, such as GDPR in Europe.

#### Can I run it on a schedule?

Yes. Create a schedule in Apify Console, daily or weekly for example, and each run delivers a fresh dataset, which you can send by email, webhook or integration.

#### Can AI agents use it?

Yes. It is available through the Apify MCP server, and every input field is described in its input schema, so an agent can call it directly.

# Actor input Schema

## `metrics` (type: `array`):

One column per metric, joined across every company that reported it. Pick two or three to start: each one is a separate call to the SEC, so ten metrics take ten times as long. Balance-sheet items are marked — they are measured at a date rather than over a period, and this Actor handles that difference for you.

## `year` (type: `integer`):

Calendar year. XBRL filings start around 2009, and the most recent quarters fill in over several months as companies file.

## `quarter` (type: `string`):

A calendar quarter, or the full year. Quarterly coverage is broader than annual, because most filers report quarterly.

## `onlyComplete` (type: `boolean`):

Off by default, because it can cut the result sharply: a company that did not tag one concept disappears entirely. Turn it on when you need a rectangular table for analysis.

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

One row per company, sorted by the sort metric.

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

Must be one of the metrics you selected. Defaults to the first one. Sorted high to low; companies missing the value sort last.

## `minValue` (type: `integer`):

For example 1000000000 to keep only companies above one billion on that metric. In the metric's own unit — dollars, shares, or dollars per share.

## Actor input object example

```json
{
  "metrics": [
    "revenue",
    "net-income",
    "assets"
  ],
  "year": 2025,
  "quarter": "Q1",
  "onlyComplete": false,
  "maxItems": 2000
}
```

# Actor output Schema

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

Every row produced by the run, in JSON.

# 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 = {
    "metrics": [
        "revenue",
        "net-income",
        "assets"
    ],
    "year": 2025,
    "quarter": "Q1",
    "maxItems": 2000
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataio/sec-edgar-xbrl-financial-screener").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 = {
    "metrics": [
        "revenue",
        "net-income",
        "assets",
    ],
    "year": 2025,
    "quarter": "Q1",
    "maxItems": 2000,
}

# Run the Actor and wait for it to finish
run = client.actor("dataio/sec-edgar-xbrl-financial-screener").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 '{
  "metrics": [
    "revenue",
    "net-income",
    "assets"
  ],
  "year": 2025,
  "quarter": "Q1",
  "maxItems": 2000
}' |
apify call dataio/sec-edgar-xbrl-financial-screener --silent --output-dataset

```

## MCP server setup

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

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/wYyjUVDl0GePeBymV/builds/fTViuGOZd08OATQ7W/openapi.json