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]

    A Financial Fact Needs Its Context

    “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.

    Three related forms of financial information
    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:

    A checklist for one usable financial fact
    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.

    One hypothetical revenue amount in two representations
    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.

    Company Facts Has a Defined Scope

    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:

    SEC endpoint patterns for a bounded retrieval
    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
    1. Define the desired fact. Write down its meaning, dates, reporting
      scope, unit and desired source vintage before opening the response.
    2. 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.
    3. Inspect the tagged statement. Locate the intended row in the
      Inline filing and inspect the concept and contextual details. Read the relevant note.
    4. Retrieve candidate observations. Use the applicable standard-taxonomy
      concept and correct unit group. Save the raw response and retrieval date.
    5. Filter by meaning, period and provenance. Match dates, form and
      accession to the task. Keep alternative observations until differences are resolved.
    6. Reconcile the chosen value. Convert presentation units once,
      check sign and scope, and confirm agreement with the readable statement.
    7. 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.

    Deriving a third quarter from consistent YTD figures
    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.

    Different filing contexts can describe a total and its parts
    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

    Machine Readable Does Not Mean Fully Interpreted

    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

    Inline XBRL embeds XBRL data in a human-readable HTML document. It connects the presentation with the structured facts, rather than removing concepts, contexts or units. Those details still need to be checked when you extract a value.

    No. The SEC describes its XBRL API aggregation as covering non-custom-taxonomy facts that apply to the entire filing entity. Custom concepts and dimensional breakdowns can require filing-level inspection. Missing from Company Facts does not mean missing from the filing or equal to zero.

    The statement may present dollars in thousands or millions while the structured fact is expressed in unscaled dollars. Confirm the unit and scale transformation. Once that transformation has occurred, do not apply the display multiplier to the resulting value again.

    Yes, when the durations share the same start date and their difference isolates the desired quarter, with matching concept, entity, scope, units and consistent reporting basis. Label the result as derived and check a directly reported quarter if available. Fiscal-period labels alone are insufficient.

    Choose according to the research question. A current historical comparison needs a consistent reporting basis, while an analysis of information available at an earlier date needs that earlier information set. Preserve provenance and investigate revised values rather than automatically replacing every observation with the latest one.

    It provides a common definition, which is valuable, but you must still compare dates, units, business scope and accounting policies. An identical tag does not align different fiscal calendars or remove economic differences between companies. Document any mapping or adjustment.

    The SEC’s public data APIs require neither an API key nor authentication. You still need to follow fair-access guidance, interpret the response and verify the selected facts. Whether another data service is useful depends on your coverage, workflow and verification needs.

    Sources

    Primary documentation accessed November 13, 2026. SEC endpoint coverage and access
    policies can change; check the current documentation before implementing automated retrieval.

    1. XBRL International: XBRL Essentials — facts, concepts, taxonomies and dimensions.
    2. SEC: Inline XBRL — readable filings and contextual tagged information.
    3. SEC: XBRL Glossary of Terms — contexts, axes, extensions and units-related terminology.
    4. XBRL International: iXBRL Tagging Features — explanatory guidance on scale and formatting; retrieved page labeled review draft.
    5. XBRL 2.1 Recommendation, corrected errata April 25, 2005 — numeric-item context/unit references and decimals accuracy.
    6. XBRL International: Positive and Negative Values in XBRL — concept meaning, presentation and balance attributes; explanatory guidance.
    7. SEC: EDGAR Application Programming Interfaces — endpoints, coverage and Frames limitations; last updated April 8, 2025.
    8. SEC: Accessing EDGAR Data — fair access, User-Agent and CIK guidance.
    9. XBRL International: Inline XBRL Part 0, Primer 1.1 — nonnormative November 18, 2013 primer on duplicates and transformations.
    10. XBRL International: XBRL Glossary — dimensions, entity-specific extensions and text blocks.
    11. 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.