SEC XBRL Financials Scraper — Revenue, Assets & EPS

---

🎯 What this scrapes

SEC's XBRL API is the fastest way to pull standardized financial facts — Revenue, Assets, NetIncomeLoss, and hundreds of other US-GAAP/IFRS/DEI concepts — straight out of company filings, but it is split across a frames endpoint (every filer, one concept, one period) and a companyconcept endpoint (one filer, full history), keyed by a taxonomy/tag/unit combination you are expected to already know, plus 10-digit CIKs instead of tickers. This Actor resolves tickers to CIKs, walks both endpoints, and normalises every fact — including the instant-vs-duration quirk where balance-sheet items carry no start date — into one flat row per company/concept/period.

🔥 What we handle for you

• 🎯 Resolves tickers to CIKs automatically — pass AAPL, get the zero-padded 10-digit CIK SEC's API expects, no manual EDGAR lookups.
• 🧩 Normalises two endpoint shapes into one row — frame mode (every filer, one period) and company mode (one filer, full history) land in the same flat schema.
• 🪧 Skips expected 404s per combination — most tag/period and company/tag pairs are legitimately unreported; the Actor logs and continues instead of crashing the run.
• 🔁 Retries with exponential backoff on 429/5xx and honours Retry-After — up to 5 attempts per request.
• 🧭 Self-throttles to SEC's fair-access expectations — a descriptive User-Agent and a bounded request rate keep every run inside SEC's published guidance.
• 🧊 Clean, typed dataset rows — Pydantic-validated, ISO-8601 timestamps, JSON/CSV/Excel export straight from the Apify Console.

💡 Use cases

• Screen every US public filer's reported Revenue or NetIncomeLoss for a given quarter in one pull.
• Backfill a fintech model with a company's full multi-year history for one accounting concept.
• Cross-check a target's reported Assets or shares outstanding before an equity research call.
• Feed a quant screener with standardized, filer-comparable facts straight from source filings.

⚙️ How to use it

1. Click Try for free at the top of the page.
2. Fill in the input form — most fields have sensible defaults.
3. Click Start. Output streams into the run's dataset.
4. Export from Storage → Dataset as JSON, CSV, or Excel — or fetch via the API.

📥 Input

Field	Type	Required	Default	Notes
mode	string	no	'frame'	Which SEC XBRL endpoint family to query: frame mode pulls every filer for one concept/period; company mode pulls one or…
taxonomy	string	no	'us-gaap'	XBRL taxonomy the concept belongs to, e.g. us-gaap, ifrs-full or dei.
tag	string	no	'Revenues'	Single XBRL concept for frame mode, e.g. Revenues, Assets or NetIncomeLoss.…
unit	string	no	'USD'	XBRL unit for frame mode, e.g. USD, USD-per-shares or shares.
periods	array	no	['CY2023Q1I']	One or more SEC frame ids, e.g. CY2023Q1I (instant), CY2023Q1 (quarterly) or…
tickers_or_ciks	array	no	[]	Tickers (e.g. AAPL) or zero-padded 10-digit CIK strings. Required when mode is company.
tags	array	no	[]	XBRL concept names to fetch per company, all under the same taxonomy. Required when mode is company.
user_agent	string	no	'DevilScrapes-XBRL/1.0 (contact: apify.com/DevilScrapes)'	SEC Fair Access requires a descriptive User-Agent naming a contact; unidentified clients get 403'd.
max_results	integer	no	50	Stop after this many financial-fact rows. Each row is one billed result.
proxy_configuration	object	no	{"useApifyProxy": false}	data.sec.gov is a plain JSON API with no anti-bot layer and does not need a proxy. Leave this off unless your account…

Example input

{
  "mode": "frame",
  "taxonomy": "us-gaap",
  "tag": "Revenues",
  "unit": "USD",
  "periods": [
    "CY2023Q1I"
  ],
  "max_results": 5,
  "proxy_configuration": {
    "useApifyProxy": false
  }
}

📤 Output

Every row is one dataset item.

Field	Type	Notes
cik	string	Zero-padded 10-digit CIK.
ticker	string	Resolved via company_tickers.json; null when not resolvable.
entity_name	string	Entity name from the SEC frame, or the resolved company title.
taxonomy	string	XBRL taxonomy, e.g. us-gaap.
tag	string	XBRL concept name.
unit	string	XBRL unit, e.g. USD.
frame	string	SEC frame id the fact came from, when applicable, e.g. CY2023Q1I.
period	string	Human label for the requested reporting period (the requested frame id in frame mode).
fiscal_year	integer	SEC's fy for this fact.
fiscal_period	string	SEC's fp, e.g. Q1, FY.
form	string	Filing form the fact was reported on, e.g. 10-K, 10-Q.
accession_number	string	SEC's accn for the source filing.
filed_date	string	ISO date the filing was submitted, SEC's filed.
start_date	string	ISO period start date; null for instant facts (common — expected, not a bug).
end_date	string	ISO period end date.
value	number	SEC's val — the reported numeric fact.
scraped_at	string	ISO 8601 UTC timestamp when the Actor fetched this row.

Example output

{
  "cik": "0000320193",
  "ticker": "AAPL",
  "entity_name": "Apple Inc.",
  "taxonomy": "us-gaap",
  "tag": "Revenues",
  "unit": "USD",
  "frame": "CY2023Q1I",
  "period": "CY2023Q1I",
  "fiscal_year": 2023,
  "fiscal_period": "Q1",
  "form": "10-Q",
  "accession_number": "0000320193-23-000006",
  "filed_date": "2023-02-03",
  "start_date": null,
  "end_date": "2022-12-31",
  "value": 117154000000.0,
  "scraped_at": "2026-08-18T12:00:00+00:00"
}

💰 Pricing

Pay-Per-Event — you pay only when these events fire:

Event	USD	What it is
actor-start	$0.05	One-off warm-up charge per run
result-row	$0.002	Per dataset item

Example: 1 000 results at the rates above ≈ $2.05. No subscription, no minimum, no card to start — Apify gives every new account $5 of free credit.

🚧 Limitations

Raw structured facts only — no derived ratios, no currency conversion; values are emitted exactly as the filer reported them, in whatever unit they used. There's no built-in catalog of valid taxonomy/tag combinations — SEC publishes no clean enumerable list, so you supply concept names directly. Financial facts update on filing cadence (quarterly/annual), not intraday.

❓ FAQ

Do I need an API key?

No. SEC publishes this data keylessly; the Actor sends the required descriptive User-Agent SEC's Fair Access policy expects and self-throttles to stay within its request-rate expectations.

Why do some tag/period or company/tag combinations return nothing?

Most XBRL tag/period pairs (frame mode) or company/tag pairs (company mode) are legitimately unreported — not every filer tags every concept every period. The Actor logs and skips these rather than failing the run.

What's the difference between frame mode and company mode?

Frame mode returns every filer's value for one concept in one period — good for cross-sectional screens. Company mode returns one or more filers' full reported history for one or more concepts — good for a time series on names you already know.

Why is start_date null on some rows?

SEC XBRL distinguishes instant facts (balance-sheet items reported as of a single date, e.g. total Assets) from duration facts (income-statement items reported over a period). Instant facts have no start date — that's expected, not missing data.

💬 Your feedback

Spotted a bug, hit a weird edge case, or need a new field? Open an issue on the Actor's Issues tab on Apify Console — we ship fixes weekly and we read every report.

---