Every public company's 10-K and 10-Q filed with the SEC after 2009 contains two versions of its financial data: the human-readable narrative and tables you see in the PDF, and a machine-readable layer of XBRL tags that labels each financial fact with its exact identity, period, and units. When a company reports $67.4 billion in annual revenue, the XBRL layer marks that specific number with the tag us-gaap:Revenues, the reporting period, the currency, and the filing context.
For investors, this structured layer is extraordinarily valuable — and largely underused. The SEC publishes all XBRL data through a free, unauthenticated API that lets you pull historical financial data for any public company or compare metrics across entire sectors in minutes. Understanding what XBRL is, what data it contains, and where its limitations lie is foundational knowledge for any investor who wants to use the SEC's data infrastructure effectively.
What XBRL Is and Why the SEC Requires It
XBRL stands for eXtensible Business Reporting Language. It's an XML-based standard developed in the early 2000s specifically for tagging financial and business reporting data. The SEC began phasing in XBRL requirements for public company filings starting in 2009, with large accelerated filers first, smaller companies following in 2011. Since 2020, the SEC has required Inline XBRL (iXBRL) for most filings — meaning the XBRL tags are embedded directly in the HTML of the filing document itself, rather than filed as a separate attachment.
The SEC's rationale was straightforward: financial data locked in PDFs is inaccessible to systematic analysis. Requiring structured tagging allows investors, researchers, regulators, and data providers to access and analyze financial information programmatically, without building proprietary databases through manual data entry. In practice, the EDGAR full-text submission database now contains XBRL data for over 7,000 active reporting companies, with historical coverage extending back 15+ years for most large-cap names.
The US-GAAP Taxonomy: The Shared Dictionary
For XBRL to enable cross-company comparison, companies need to use the same tag names for the same concepts. That's the role of the US-GAAP taxonomy — a standardized dictionary of over 17,000 financial concepts maintained by the Financial Accounting Standards Board (FASB). When Apple reports revenue and Microsoft reports revenue, both use the tag us-gaap:Revenues (or us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax under ASC 606). This shared vocabulary makes programmatic comparison possible.
The core US-GAAP taxonomy covers:
- Income statement concepts: Revenues, cost of revenue, gross profit, operating expenses by category (R&D, SG&A), operating income, interest expense, income before tax, income tax expense, net income, EPS (basic and diluted)
- Balance sheet concepts: Cash and equivalents, receivables, inventory, total current assets, property/plant/equipment, goodwill, intangible assets, total assets; accounts payable, short-term debt, total current liabilities, long-term debt, total liabilities, stockholders' equity
- Cash flow statement concepts: Operating cash flow, depreciation and amortization, capital expenditures, free cash flow components, financing activities (debt issuance/repayment, share repurchases, dividends)
- Per-share data: Basic and diluted EPS, book value per share, dividends per share
- Shares outstanding: CommonStockSharesOutstanding and related concepts
Custom Extension Tags: The Cross-Company Comparison Problem
The US-GAAP taxonomy covers standard concepts, but companies frequently report metrics that don't fit standard tags. A software company reporting "Annual Recurring Revenue" or a REIT reporting "Funds From Operations" will create a custom extension tag — a company-specific XBRL label that has no equivalent in the US-GAAP taxonomy. These extension tags appear in the filing with a company-specific prefix (e.g., aapl:ServiceRevenue) instead of the standard us-gaap: prefix.
This is the single biggest limitation for cross-company XBRL comparison. Extension tags cannot be systematically compared across companies without additional mapping work. For standardized metrics — revenue, net income, total assets, operating cash flow — US-GAAP taxonomy tags work reliably. For non-GAAP metrics, segment data with unique labels, or company-defined operational metrics, extension tags require case-by-case handling.
How to Access XBRL Data Through the SEC EDGAR API
The SEC provides three primary XBRL API endpoints, all free and requiring no authentication (only a descriptive User-Agent header in requests):
1. Company Facts API (All Facts for One Company)
The most useful endpoint for investors analyzing a single company. Returns every XBRL-tagged fact ever filed by a company — organized by concept, then by form type, then by period:
https://data.sec.gov/api/xbrl/companyfacts/CIK{10-digit-padded-CIK}.json
Example (Apple, CIK 0000320193):
https://data.sec.gov/api/xbrl/companyfacts/CIK0000320193.json
The response is a large JSON object structured as: facts → {taxonomy} → {concept} → {label, description, units → {unit → [{value, end, form, filed, accn}]}}. Each entry gives the reported value, the period end date, the form type (10-K, 10-Q), and the filing accession number for source verification.
To find a company's CIK, use the EDGAR company search at https://www.sec.gov/cgi-bin/browse-edgar?company={name}&CIK=&type=10-K&action=getcompany, or look it up in the EDGAR full-text search. TL;DR Filing's search and company pages also display CIK numbers for easy lookup.
2. Company Concept API (One Metric, All Historical Periods)
Pulls a single financial concept for one company across all filing periods — the most direct way to build a historical time series for a specific metric:
https://data.sec.gov/api/xbrl/companyconcept/CIK{id}/us-gaap/{concept}.json
Example — Apple annual revenues:
https://data.sec.gov/api/xbrl/companyconcept/CIK0000320193/us-gaap/Revenues.json
This endpoint is ideal for building financial models: pull 10 years of operating cash flow, capital expenditures, or revenue for a company in a single API call. The response separates quarterly (10-Q) and annual (10-K) filings, and includes both the instantaneous value (for balance sheet items at period end) and duration values (for income/cash flow items over a period).
3. Frames API (One Metric, All Companies, One Period)
The sector-comparison tool. Returns a specific financial concept for every XBRL-filing company for a specific reporting period — enabling systematic cross-sectional analysis:
https://data.sec.gov/api/xbrl/frames/us-gaap/{concept}/{unit}/{period}.json
Example — All companies' annual revenues for fiscal year 2024:
https://data.sec.gov/api/xbrl/frames/us-gaap/Revenues/USD/CY2024.json
The period format uses "CY" (calendar year) or "CY{year}Q{quarter}I" for quarterly instant values (balance sheet items). This endpoint powers systematic screening — identifying every company with revenue above a threshold, every company where capital expenditures exceeded operating cash flow in a given year, or every company where goodwill exceeds 50% of total assets.
Reading XBRL Data: What the Numbers Actually Mean
Raw XBRL data requires some interpretation to use correctly. The key fields in any XBRL fact:
| Field | Meaning | Investor implication |
|---|---|---|
| val | The reported number | Usually in the unit shown (USD, shares); NOT pre-scaled — Apple's revenue appears as ~391000000000, not $391B |
| end | Period end date | For income/cash flow: end of the reporting period. For balance sheet: the "as of" date. |
| start | Period start date (duration facts only) | Use end minus start to determine whether a fact covers 3 months (quarterly) or 12 months (annual) |
| form | Filing type (10-K, 10-Q, 8-K, etc.) | Filter to 10-K for annual comparisons; 10-Q for quarterly. Avoid 8-K amendments which may restate data. |
| filed | Date the filing was submitted to EDGAR | Use to identify most recent data; multiple facts for the same period may exist if restated (take the latest filed date) |
| accn | Accession number (links to source filing) | Use to fetch the original filing for context verification: https://www.sec.gov/Archives/edgar/data/{cik}/{accn} |
Annual vs. Quarterly Data: A Critical Distinction
Income statement and cash flow concepts appear in XBRL with both annual and quarterly values — and they can be confusing. A company with a September fiscal year-end will have a 10-K filing reporting 12-month revenue. Its quarterly 10-Qs report 3-month figures. Both appear in the same XBRL concept with different period durations. When building a multi-year revenue chart, filter to facts where the period duration is approximately 12 months (365 days) to isolate annual figures, or approximately 90 days for quarterly.
Balance sheet concepts (total assets, total debt, cash) are "instantaneous" facts — they represent the balance at a single point in time, not over a period. These have an end date but no start date in the XBRL data.
Practical Investor Use Cases for XBRL Data
1. Building a 10-Year Financial Summary Without a Data Terminal
Investment data terminals (Bloomberg, FactSet, Capital IQ) cost $25,000–$50,000+ per year. The SEC XBRL API provides the raw material for equivalent historical financial data at zero cost. Using the Company Concept API, an investor can pull annual revenue, operating income, net income, operating cash flow, and capital expenditures for any public company going back 10–15 years in a few API calls, build a free cash flow time series, and calculate CAGR — all without a data subscription.
The workflow: (1) Look up the company's CIK via EDGAR. (2) Use the Company Concept API to pull the relevant concepts. (3) Filter to annual 10-K filings. (4) Sort by period end date. (5) Build the financial model. See our how to analyze company financials guide for the full framework this data feeds into.
2. Sector-Wide Screening for Specific Financial Characteristics
The Frames API enables screening that would otherwise require a proprietary financial database. Examples of questions you can answer with a single API call and basic filtering:
- Which S&P 500 companies had free cash flow yield above 8% in fiscal year 2024?
- Which companies in the semiconductor sector had gross margins above 60%?
- Which companies increased capital expenditures by more than 50% year-over-year?
- Which companies have goodwill exceeding 40% of total assets (acquisition risk)?
The Frames API returns data for all EDGAR filers, not just S&P 500 constituents — so you'd need to filter by sector or index membership separately. SEC EDGAR company search can filter by SIC code (industry classification), providing a rough sector cut.
3. Restatement Detection
When a company restates earnings, it refiles the affected period with corrected XBRL data. This means the EDGAR XBRL database will contain multiple values for the same concept and period — the original filing and the restated filing — both linked to different accession numbers. Investors can detect restatements by checking whether any concept has more than one value for the same period end date; if so, the later-filed value supersedes the earlier one, and the original value represents the pre-restatement figure. See our red flags guide for the full restatement pattern and its investment implications.
4. Tracking Management Guidance Against Actual Results
XBRL captures what companies actually reported — not management's forward guidance. But by building a multi-year XBRL data series and comparing it against the guidance management provided in MD&A sections of prior-year filings, investors can assess guidance accuracy over time. Companies that systematically over-promise (positive guidance, disappointing actuals) versus under-promise (conservative guidance, beat-and-raise) show different patterns that affect how to weight their forward statements. Our MD&A and management guidance guide covers the interpretation framework; XBRL provides the objective actuals to benchmark against.
5. Identifying When a Company Changed Its Accounting
Accounting policy changes — revenue recognition methodology under ASC 606, lease capitalization under ASC 842, pension accounting adjustments — create discontinuities in XBRL time series that can be mistaken for underlying business changes. A revenue jump in 2019 for many companies reflects ASC 606 adoption, not organic growth. A sudden increase in long-term assets in 2019–2020 for many companies reflects right-of-use asset recognition under ASC 842. When building XBRL-based financial histories, watch for these standard transition dates that affect most companies simultaneously.
XBRL Taxonomy Concepts Investors Use Most
| US-GAAP Concept Tag | What it measures | Notes |
|---|---|---|
| Revenues | Total revenues | Check if company uses RevenueFromContractWithCustomerExcludingAssessedTax instead (post-ASC 606) |
| GrossProfit | Revenue minus cost of goods sold | Divide by Revenues for gross margin % |
| OperatingIncomeLoss | EBIT (before interest and tax) | May include or exclude restructuring charges depending on company |
| NetIncomeLoss | Bottom-line net income | Attributable to parent entity (excludes minority interest for consolidated filers) |
| EarningsPerShareDiluted | Diluted EPS | Most commonly used for P/E analysis; basic EPS in EarningsPerShareBasic |
| NetCashProvidedByUsedInOperatingActivities | Operating cash flow | Full name is long; use as denominator check for net income quality (OCF/NI ratio) |
| PaymentsToAcquirePropertyPlantAndEquipment | Capital expenditures (cash flow) | Subtract from operating cash flow to compute free cash flow |
| CashAndCashEquivalentsAtCarryingValue | Cash and equivalents (balance sheet) | Instantaneous fact; add ShortTermInvestments for total liquidity |
| LongTermDebt | Long-term debt | Add ShortTermBorrowings for total debt; compare against EBITDA for leverage ratio |
| Goodwill | Goodwill from acquisitions | Divide by total assets for goodwill intensity; watch for impairment charges in OperatingIncomeLoss |
| CommonStockSharesOutstanding | Basic shares outstanding | Instantaneous fact; use to compute market cap when combined with price data |
| StockholdersEquity | Total shareholders' equity | Divide by shares outstanding for book value per share; negative equity signals balance sheet stress |
Limitations Every Investor Should Know
1. Extension Tags Break Cross-Company Comparison
When companies create custom extension tags for non-standard metrics, those facts cannot be compared across companies using the US-GAAP taxonomy. Large technology companies routinely create extension tags for cloud revenue segments, deferred revenue breakdowns, and platform metrics. For standardized financial statement line items (revenue, net income, total assets), US-GAAP tags work reliably; for anything below the financial statement level, assume extension tags and verify.
2. Restatements Create Duplicate Values
If a company restates a financial period, EDGAR will contain two XBRL values for the same concept and period end date. The later-filed value is the restated (correct) figure. Naive API queries that don't account for restatements will include both values in a time series. Always select the most recently filed value for each period when building financial models from raw XBRL data.
3. Tagging Errors Exist, Especially in Smaller Filers
The SEC's EDGAR system validates XBRL submissions against the taxonomy but does not catch all mapping errors. Smaller filers without dedicated XBRL preparation staff sometimes apply incorrect tags — using a concept that's approximately right but not technically correct for their disclosure. For large-cap companies with dedicated financial reporting teams, tagging quality is generally high. For micro-cap and smaller filers, spot-check XBRL values against the filing document for any metric that will influence an investment decision.
4. Narrative and Notes Are Not Tagged
XBRL captures financial statement line items and certain disclosures, but the qualitative content that experienced investors value most — management's explanation of why margins declined, new risk factor language added in response to an emerging problem, the specific terms of a debt covenant — is not systematically tagged. For narrative analysis, the filing text must still be read directly. XBRL and text-based analysis are complementary, not substitutes. See our 10-K analysis checklist for how to combine both approaches efficiently.
5. Historical Coverage Has Gaps
XBRL coverage for large accelerated filers begins in 2009; smaller reporting companies began in 2011. Companies that went private, were acquired, or delisted before completing their full filing cycle may have incomplete XBRL histories. Non-US companies that file on Form 20-F use the IFRS taxonomy rather than US-GAAP, meaning cross-comparison between US and international companies requires taxonomy mapping. The SEC EDGAR API does include IFRS-tagged data, but concept names differ from US-GAAP equivalents.
XBRL Data in the Context of AI-Powered Analysis
XBRL structured data and AI language models are complementary tools for financial analysis. AI excels at reading and interpreting the narrative portions of filings — the MD&A, risk factors, and footnote disclosures — where XBRL has no coverage. XBRL excels at providing precise, machine-readable financial facts that can be queried programmatically, compared across companies, and fed into quantitative models — tasks where LLMs hallucinate or hit context limits on long documents.
The most powerful analytical workflow combines both: use XBRL to build the quantitative foundation (financial time series, cross-company comparisons, anomaly detection), then use AI-assisted text analysis on the filing narrative to understand why the numbers look the way they do. Our AI and financial analysis guide covers the specific AI use cases in more detail; XBRL provides the structured data layer that makes those workflows more reliable.
Purpose-built financial platforms (AlphaSense, Sentieo, Bloomberg Terminal) combine both approaches with additional data curation and error correction on top of the raw EDGAR XBRL feed. For individual investors and independent researchers, the raw SEC EDGAR XBRL API provides access to the same underlying data without the subscription cost — at the cost of requiring more data engineering to handle edge cases like restatements, extension tags, and tagging errors.
The Bottom Line
XBRL is the SEC's most underused gift to individual investors. The same structured financial data that institutions pay tens of thousands of dollars for via Bloomberg or FactSet is available free through the EDGAR API, covering every public US company going back 15+ years. The barriers are not legal or financial — they're technical: understanding the taxonomy, handling edge cases in the data, and building the query workflow to extract what you need.
For investors comfortable with a basic programming environment (Python, JavaScript, or even a spreadsheet with API queries), the EDGAR XBRL API opens systematic financial analysis that was previously only available to institutions. For investors who prefer not to write code, tools like TL;DR Filing surface the same underlying XBRL data in a readable, structured format tied directly to each company's filing history — without requiring you to navigate the raw API responses yourself.
Related Guides
- How to Analyze a 10-K Filing Fast: Investor's Practical Checklist
- How to Analyze Company Financials: Step-by-Step Framework
- Red Flags in SEC Filings: 15 Warning Signs Every Investor Must Know
- How AI Is Changing Financial Analysis: What Investors Need to Know
- How to Read MD&A and Interpret Management Guidance (2026)
- 10-K vs 10-Q vs 8-K: Which SEC Filing Matters Most?
Frequently Asked Questions
What is XBRL in SEC filings?
XBRL (eXtensible Business Reporting Language) is a structured data format that tags financial facts in SEC filings with standardized labels. When a company reports revenue of $10 billion, the XBRL tag us-gaap:Revenues marks that exact value with its period, units, and filing context. This makes the data machine-readable and enables programmatic comparison across thousands of companies without reading each filing manually.
How do I access XBRL data from SEC EDGAR?
The SEC's EDGAR API provides free, unauthenticated XBRL access. The Company Facts API (data.sec.gov/api/xbrl/companyfacts/CIK{id}.json) returns all historical XBRL facts for one company. The Company Concept API returns one financial metric across all periods. The Frames API returns one metric across all companies for one period. No API key is required — include a descriptive User-Agent header per SEC guidelines.
What financial data is available through XBRL?
XBRL covers the full financial statements: income statement (revenues, gross profit, operating income, net income, EPS), balance sheet (assets, liabilities, equity, debt, cash), and cash flow statement (operating cash flow, capex, financing activities). Segment data and certain disclosures are also tagged when companies use standard taxonomy concepts. Narrative disclosures, risk factors, and MD&A text are not tagged.
What are the limitations of XBRL data?
Key limitations: custom extension tags prevent cross-company comparison on non-standard metrics; restatements create multiple values for the same period (always use the most recent filing date); tagging errors exist in smaller filers; narrative disclosures are not structured; and historical coverage begins in 2009–2011 depending on company size. Cross-border comparison between US-GAAP and IFRS filers requires taxonomy mapping.
How is XBRL useful for comparing companies?
XBRL enables systematic sector-wide comparison using the Frames API — pulling revenue, margins, or debt metrics for every public company in a given period simultaneously. For standardized financial statement concepts using US-GAAP taxonomy tags, comparison is reliable and programmatic. This capability was previously only accessible through expensive data terminal subscriptions; the SEC EDGAR API provides equivalent data access at no cost.