← All guides

What is XBRL, and why is it a pain?

XBRL is how the numbers inside SEC filings become machine-readable. Here's how it works, why it hurts, and how to skip the worst of it.

XBRL (eXtensible Business Reporting Language) is the tagging system that turns the numbers in a filing into structured data. When Apple reports "revenue was $102,466,000,000," XBRL is what makes that readable as Revenues: 102466000000 instead of text in a table.

The basic idea

Every tagged number is a fact, and a fact has four parts:

  1. A concept: what the number means, picked from a taxonomy. The main one is us-gaap (US accounting standards). There's also dei for entity info like company name and ticker.
  2. A value: the number itself, or text for things like entity names.
  3. A context: the period it covers. Assets is an instant ("as of Sept 27, 2025"), while Revenues is a duration ("for the 12 months ended Sept 27, 2025"). Same tag, different meaning.
  4. A unit: USD, shares, USD-per-share.

So one fact reads like: "us-gaap:Revenues, USD, 12 months ending 2025-09-27 = 102,466,000,000."

Inline XBRL

Since 2019, most companies file inline XBRL (iXBRL): the tags are embedded directly in the human-readable HTML. One document serves both humans and machines. Nice in theory. In practice it means the structured data is scattered through a giant HTML file instead of sitting in a clean XML blob.

Why it's a pain

  • Tags aren't consistent. Companies pick different concepts for the same line item. "Revenue" might be Revenues, RevenueFromContractWithCustomerExcludingAssessedTax, or SalesRevenueNet. Sometimes all three across different years.
  • Extensions. If no standard tag fits, a company can invent its own (aapl:SomethingCustom). Great for accuracy, terrible for querying across companies.
  • Restatements. Companies re-tag old numbers. The "revenue for FY2023" you pulled last year might not match what the latest filing says for FY2023.
  • Contexts multiply. One tag can appear with a dozen contexts: fiscal year, quarter, segment breakdowns, geographic slices. Picking "the" revenue number means filtering all that out.
  • Duration vs. instant confusion. Sum four quarters of a duration tag and compare to the annual value and you'll occasionally get a mismatch, because companies report YTD and quarterly values both.

None of this is exotic edge-case stuff. It's the everyday reality of the data.

Skipping the wrangling

The raw layer is still useful when you need it. /v1/companies/:cik/facts gives you a company's full fact history, filterable by tag, unit, form, and period:

GET /v1/companies/0000320193/facts?tag=Assets
GET /v1/facts?tag=Revenues&end=2025-09-30&unit=USD   # every company, one quarter

But most of the time you don't want facts, you want a statement. /v1/companies/:cik/financials normalizes the fact soup into income statement, balance sheet, or cash flow line items:

GET /v1/companies/0000320193/financials?statement=income&period=annual&limit=8
GET /v1/companies/0000320193/financials?statement=cashflow&period=quarterly

The cash flow statement includes a computed freeCashFlow line. If you've ever hand-rolled "operating cash flow minus capex" across inconsistent tag names, you know why that's nice to have.

More on the endpoints in the docs.

Pull this data straight from the API

Free tier includes 50 credits a month. One credit per request.

Get an API key