XBRL: Facts, Tags and SEC Data
Table of Contents
XBRL makes financial statements usable as structured data by attaching
meaning and reporting context to individual facts. That can save an analyst from copying
hundreds of numbers by hand. It can also move a wrong number into a model very efficiently
if the analyst chooses the wrong period, unit, segment or filing version.
The practical goal is to retrieve one fact and explain exactly what it represents.
This guide follows that task from a human-readable statement to a tagged value, then shows
how to check SEC Company Facts data before comparing companies or reporting periods.
The examples are hypothetical; the SEC access information was checked on November 13, 2026.
What Is XBRL?
XBRL stands for eXtensible Business Reporting Language. A reporting concept
defines what a fact means, while a taxonomy provides a collection of concepts and their
relationships. A reported fact associates a value with that meaning and with information
such as the entity, period and measurement unit.[1]
“Revenue: 900” is incomplete. You need to know whose revenue it is, the dates
covered, the currency and scale, whether it covers the whole company or a segment,
and which filing supplied the figure.
Think of a taxonomy tag as a defined measurement, rather than a convenient row label.
Two rows both labeled “revenue” deserve a closer look if their definitions or coverage differ.
Conversely, different presentation labels can refer to the same underlying concept.
This is the data foundation beneath fundamental analysis.
It helps you identify the reported inputs; interpreting the business still requires reading
the statements and their notes.
XBRL vs. Inline XBRL and SEC JSON
Inline XBRL, often written iXBRL, embeds structured facts in a
human-readable HTML document. The SEC’s viewer lets readers inspect contextual details
behind tagged points, including definitions and reporting periods.[2]
The SEC’s JSON APIs offer another way to consume selected extracted facts.
| Form | What it provides | Best use here |
|---|---|---|
| XBRL data | Facts with concepts, contexts and units | Identify what each value measures |
| Inline XBRL filing | Readable presentation with embedded structured facts | Trace a tagged value to its statement and notes |
| SEC Company Facts JSON | An API aggregation with defined coverage limits | Find candidate observations for a company |
A Company Facts response is useful for discovery and analysis, but it is not the entire
Inline filing converted into a complete company model. Preserve a route back to the filing
whenever a number enters your analysis.
The Information That Identifies a Fact
Before retrieving data, decide what you want to measure. For example, “consolidated
revenue for the nine months ended September 30, 2025, in U.S. dollars, on the latest
comparable reporting basis” is a workable target. “Latest revenue” leaves crucial choices open.
In an XBRL filing, the context identifies entity and period information and can include
dimensional qualifications. Numeric facts separately reference a unit. Dimensions, also
called axes, distinguish breakdowns such as business segments or geography.[3]
Check the following information together:
| Check | Question to answer |
|---|---|
| Entity | Which legal filer and reporting group does this describe? |
| Concept and taxonomy | What is the definition, namespace and relevant taxonomy version? |
| Period | Is this an instant or a duration? What are the actual dates? |
| Scope and dimensions | Is it consolidated, parent-only, a segment, a geography or another breakdown? |
| Unit and representation | USD, another currency, shares, or currency per share? Has display scaling already been applied? |
| Filing provenance | Which form, accession and filing date supplied it? Which version does the analysis need? |
The same concept can have many valid observations. An annual figure, a nine-month
figure and a three-month figure ending on the same date answer different questions.
For the economic role of stocks and flows, review how the
three financial statements fit together.
Instant vs. Duration
An instant describes a position at a date, such as cash at December 31.
A duration describes activity over an interval, such as revenue from January 1
through December 31. A period-end date alone cannot tell you how many months a flow covers.
Do not treat a fiscal-year or fiscal-period label as a substitute for those dates.
A filing can present current and comparative periods, and its fiscal labels do not turn
every included observation into the current quarter. Start with the measurement interval.
Reconciling the Displayed Row and the Structured Value
Suppose hypothetical Harbor Components reports annual revenue for January 1 through
December 31, 2025. Its consolidated statement says “USD in millions”, and the
revenue row displays 1,200. Assume its Inline tagging uses a scale of 6 and
the extracted monetary fact is denominated in USD.
The following teaching record uses demo:Revenue and
FY2025_Consolidated as invented explanatory labels. They are not actual SEC
taxonomy identifiers or a downloadable API response. “Filing A” represents one hypothetical
source submission; real work should retain its actual accession number.
| Item | Human-readable statement | Structured interpretation |
|---|---|---|
| Meaning | Revenue | Illustrative concept: demo:Revenue |
| Reporting context | Consolidated; year ended December 31, 2025 | FY2025_Consolidated; January 1–December 31, 2025 |
| Displayed amount | 1,200 under “USD in millions” | Scale 6 converts the display to dollars |
| Monetary fact | $1.2 billion | 1,200,000,000 USD |
| Provenance | Statement in Filing A | Same Filing A; preserve the real accession in practice |
The displayed 1,200 and the structured 1,200,000,000 agree:
1,200 × 106 = 1,200,000,000 USD.
Inline scaling converts a readable presentation to the unscaled fact; it does not create
additional revenue.[4]
Scale Is Different from Accuracy
A scale of 6 means multiply the displayed magnitude by one million during extraction.
An accuracy attribute such as decimals="-6" describes million-dollar accuracy.
It does not instruct you to multiply an extracted value again.[5]
For an already unscaled USD value, divide by one million if you want to display USD millions.
Applying the statement’s million-dollar display scale to an API value already expressed
in USD would inflate the number by a factor of one million. More trailing zeros in a
structured representation also do not mean the underlying report was accurate to the dollar.
Check Sign Meaning Separately
A printed expense in parentheses can be a deduction in the statement while its tagged
concept represents a positive expense amount. Read the concept definition and the Inline
sign information. A debit/credit balance attribute describes the concept’s accounting
nature; it is not a rule to flip every fact with that attribute.[6]
Reconcile the statement’s calculation after understanding that distinction. Do not
“repair” a sign solely because the screen presentation and structured value look different.
How to Retrieve and Validate SEC Company Facts
The SEC provides public JSON APIs without an API key or authentication. Company Concept
returns observations for one company and concept, separated by measurement unit; Company
Facts gathers that company’s concept data in one response.[7]
Use them to assemble candidates, then make an explicit selection.
The SEC’s XBRL APIs aggregate facts using non-custom taxonomies that apply to the
entire filing entity. Do not expect Company Facts to reproduce all custom extension
concepts, segment breakdowns, footnotes or other tagged content in a filing.
These are endpoint patterns, not executable requests. Replace {CIK10}
with the filer’s 10-digit CIK, including leading zeros. Replace the taxonomy and concept
placeholders with identifiers actually found and checked in the filing:
| Purpose | URL pattern |
|---|---|
| Filing history | https://data.sec.gov/submissions/CIK{CIK10}.json |
| One concept | https://data.sec.gov/api/xbrl/companyconcept/CIK{CIK10}/{taxonomy}/{concept}.json |
| Company concepts | https://data.sec.gov/api/xbrl/companyfacts/CIK{CIK10}.json |
- Define the desired fact. Write down its meaning, dates, reporting
scope, unit and desired source vintage before opening the response. - Identify the filer and source filing. Confirm the CIK and company
identity. Record the filing form, date and accession; do not rely on a ticker alone. - Inspect the tagged statement. Locate the intended row in the
Inline filing and inspect the concept and contextual details. Read the relevant note. - Retrieve candidate observations. Use the applicable standard-taxonomy
concept and correct unit group. Save the raw response and retrieval date. - Filter by meaning, period and provenance. Match dates, form and
accession to the task. Keep alternative observations until differences are resolved. - Reconcile the chosen value. Convert presentation units once,
check sign and scope, and confirm agreement with the readable statement. - Preserve the selection. Save the original observation plus your
selection rule, any transformation and the filing location supporting it.
If the needed fact falls outside Company Facts coverage, return to the filing and its
tagged information. An absent API observation is not evidence that the company reported zero.
Access EDGAR Responsibly
As of the research date, SEC fair-access guidance sets a maximum of
10 requests per second and asks automated users to declare a User-Agent
identifying the organization/name and administrative contact email. The SEC asks users to
download only what they need and moderate requests.[8]
For a small analysis, request sparingly, reuse saved responses and back off when access
is limited. The ceiling is not a target or a guarantee of service. This article provides no
scraper or production client; check current SEC guidance before implementing one.
Quarterly vs. Year-to-Date Facts
Consider a separate hypothetical calendar-year company. It reports revenue of
$900 million for January–September 2025 and
$600 million for January–June 2025. Assume the concept, entity,
currency, reporting scope and accounting basis match and the two figures use consistent
filing versions. The question is revenue for July–September alone.
| Measurement interval | Revenue (USD millions) | Treatment |
|---|---|---|
| January–September | 900 | Nine-month reported input |
| January–June | 600 | Subtract matching six-month input |
| July–September | 300 | Derived: 900 − 600 |
The third-quarter result is $300 million. Label it as derived if you
calculated it, and compare it with a directly reported three-month figure when available.
The same September end date does not make the nine-month 900 a quarterly observation.
This subtraction works because the shorter duration is the beginning portion of the
longer one on a consistent basis. It does not work merely because the observations carry
“Q2” and “Q3” labels. It is also not a method for turning two cash balances into revenue.
Filing Vintage Can Change the Result
Now suppose a later filing presents the comparable six-month amount as
$620 million, and its consistent nine-month amount is still $900 million.
The later-basis calculation is 900 − 620 = $280 million.
Using the earlier 600 would give 300, overstating that derived quarter by $20 million.
Investigate why a comparative value changed: a restatement, reclassification or another
reporting change can require different handling. A changed value is a reason to read the
explanation, rather than automatically label the earlier filing erroneous.
For current historical comparison, use a documented consistent reporting basis. For
research asking what was knowable at an earlier date, preserve the filings and figures
available by that cutoff. A recently retrieved response is not, by itself, a record of what
an investor could have known then.
Segments and Repeated Facts Are Different Problems
Return to the hypothetical nine-month revenue of $900 million. This time, suppose a
filing also reports North segment revenue of $540 million and South segment revenue of
$360 million for the same dates. Assume these segments exhaust revenue, do not overlap
and need no elimination or other reconciliation adjustment.
| Filing-level context | Revenue (USD millions) | Relationship |
|---|---|---|
| Consolidated company | 900 | Total |
| North segment | 540 | Part of that total |
| South segment | 360 | Part of that total |
The parts reconcile as 540 + 360 = 900. Summing all three facts gives
1,800 and counts the revenue twice. This table illustrates filing-level dimensions;
it does not depict Company Facts returning a complete segment dataset.
In real segment reporting, examine the actual
reconciliation. Intersegment amounts, corporate items and other adjustments can prevent
a simple sum. Likewise, verify the reporting boundary before using a parent-only amount
as though it came from consolidated financial statements.
A repeated fact is another issue. A value can appear more than once in a filing, and
a later filing can repeat an earlier comparative period. Those occurrences do not create
new economic activity.[9]
Compare the full fact identity and provenance before deduplicating; investigate conflicting
values rather than averaging them or keeping the last array element automatically.
Standard Tags vs. Custom Extensions
Standard concepts provide a common vocabulary. Entity-specific extensions let preparers
express disclosures that require their own concepts or dimensions. An extension is not
inherently a bad tag, and a familiar-looking label does not establish its equivalence to a
standard concept.[10]
Standard Concept
- Starts with a shared definition
- Helps locate potentially comparable facts
- Still requires matching periods, units and reporting scope
Entity-Specific Extension
- Captures a particular reporting need
- Requires reading its definition and relationships
- May require a documented mapping before comparison
For cross-company work, keep a mapping note explaining why two concepts measure the
same intended item and where their coverage differs. Check accounting policies, gross-versus-net
presentation, continuing operations, currencies and fiscal calendars. Matching tag names is
a starting point, not sufficient evidence for a sound comparable companies analysis.
The SEC’s Frames API can help assemble a cross-entity starting set, but it selects
facts that best fit calendar periods; actual reporting dates can differ. Before interpreting
a difference in revenue or margins, establish that the underlying measurement periods and
business scope support the comparison.
Common Mistakes with XBRL Financial Data
- Picking the most recently filed observation without checking dates.
A new filing can repeat an old period. Select the target interval and source basis. - Multiplying an unscaled value by “millions” again.
Separate display conversion from the monetary unit of the extracted fact. - Deleting differences as duplicates.
Segment, geography and consolidated contexts can legitimately differ. - Filling missing observations with zero.
Establish whether the fact is absent, outside API coverage or reported elsewhere. - Applying one sign rule to every statement.
Follow concept meaning and reconcile presentation and calculations. - Mixing revised and original YTD inputs.
Preserve a consistent reporting basis and label calculated quarters.
Once the fact is validated, retain those choices with any downstream
financial ratio analysis. A correct ratio formula
cannot compensate for an input measuring a different period or reporting entity.
Limitations of Structured Financial Data
A valid format and a successful download do not prove that the selected fact is
appropriate for your question. Footnotes, measurement definitions and reporting changes
can matter as much as the number.
Coverage depends on the specific data product. A narrative note may be tagged as one
text block without making every embedded number a separate numeric fact. Do not transfer
one API’s coverage assumptions to all SEC downloads.
For example, the SEC’s separate Financial Statement Data Sets have their own scope
and processing history. The SEC warns that those datasets can contain errors and omit
information, and that they do not replace the underlying filings.[11]
Use a dataset according to its own documentation.
A useful stopping point is a small, auditable record: the selected fact, its definition
and context, the source filing, your selection rule and any conversion or derivation.
That record makes the next analysis easier to reproduce and disagreements easier to resolve.
Frequently Asked Questions
Sources
Primary documentation accessed November 13, 2026. SEC endpoint coverage and access
policies can change; check the current documentation before implementing automated retrieval.
- XBRL International: XBRL Essentials — facts, concepts, taxonomies and dimensions.
- SEC: Inline XBRL — readable filings and contextual tagged information.
- SEC: XBRL Glossary of Terms — contexts, axes, extensions and units-related terminology.
- XBRL International: iXBRL Tagging Features — explanatory guidance on scale and formatting; retrieved page labeled review draft.
- XBRL 2.1 Recommendation, corrected errata April 25, 2005 — numeric-item context/unit references and decimals accuracy.
- XBRL International: Positive and Negative Values in XBRL — concept meaning, presentation and balance attributes; explanatory guidance.
- SEC: EDGAR Application Programming Interfaces — endpoints, coverage and Frames limitations; last updated April 8, 2025.
- SEC: Accessing EDGAR Data — fair access, User-Agent and CIK guidance.
- XBRL International: Inline XBRL Part 0, Primer 1.1 — nonnormative November 18, 2013 primer on duplicates and transformations.
- XBRL International: XBRL Glossary — dimensions, entity-specific extensions and text blocks.
- SEC: Financial Statement Data Sets — separate dataset scope and limitations; updated September 30, 2026.
Disclaimer
This article is for educational and informational purposes only and does not
constitute investment, legal or accounting advice. All worked company amounts and
filing-version examples are hypothetical. Verify data against the underlying filings
and current documentation before relying on it for an investment or reporting decision.
Keep reading
More in Financial Modeling
-
DCF Valuation & Comparable Company Analysis: A Practitioner Guide
How investment bankers and analysts value companies using discounted cash flow analysis, comparable company analysis (trading comps), and precedent…
-
Pro Forma Financial Statements: Percent-of-Sales Method, EFN & Growth Rate Formulas
Learn how to build pro forma financial statements using the percent-of-sales method, calculate external financing needed (EFN), and determine sustainable…
-
LBO Model Fundamentals: Structure, Returns & the Mechanics of Leveraged Buyouts
Master LBO model mechanics: Sources & Uses construction, debt schedule, IRR/MOIC calculation, the five return drivers, exit assumptions, and sensitivity…
