What an XBRL tag is, and why revenue is hard to find

A fact is four things, and the value is the least interesting

Structured filing data is built from facts. Each one carries a value, a concept, which is the taxonomy tag such as a us-gaap element; a context, which fixes the reporting entity and the period; and a unit, usually USD or USD per share. Periods come in two shapes and confusing them is the most common error in the entire subject: a duration has a start and an end and describes a flow such as revenue, while an instant has a single date and describes a balance such as cash.

A number with no context is not data. "Revenue was 24.9 billion" is not reproducible; the same value with a tag, a start date, an end date, a form type, and an accession number is, and anyone can open the filing and see it. This is the difference between quoting a figure and citing one.

Revenue is not one tag

The us-gaap taxonomy has carried several revenue concepts over the years. Revenues is the broad one. RevenueFromContractWithCustomerExcludingAssessedTax and its including-assessed-tax sibling arrived with the current revenue recognition standard and are what most filers use now. Older filings use elements that have since been deprecated. And any company can define an extension element for something the standard taxonomy does not express, which is legitimate and also means no single query covers every filer.

So a revenue series assembled by asking for one tag will have holes, and a series assembled by taking whatever revenue-shaped tag is present will silently switch definitions mid-series. The workable approach is a priority list of standard tags evaluated in order, with the tag actually used recorded next to every value so a definition change is visible rather than smoothed over.

The five ways the query returns the wrong number

Year-to-date against quarter: a 10-Q reports both a three-month and a nine-month duration, and taking the newest row without checking the length of the period puts a cumulative figure next to a quarterly one. Q4 does not exist: annual filings report the full year, so the fourth quarter has to be derived by subtracting the first three from the annual figure. Amendments: a 10-K/A supersedes values you may already have stored under a different accession. Restatements: a later filing can carry a revised figure for a prior period, so a value is only ever true as of the filing that reported it. And dimensions: the consolidated figure is not the segment figure, and a segment split has to come from the filing rather than from a top-level facts query.

• Check the unit before anything else.
• Confirm the start and end dates describe the period you think they do.
• Derive Q4 by subtraction rather than looking for a filing that does not exist.
• Store the tag, form, filing date, and accession beside every value.
• Prefer the original filing’s value, and record later restatements separately.

Pulling it yourself, politely

The SEC exposes company facts and company concept endpoints keyed by CIK, which return every reported value for a company or for one concept, along with the period, form, filing date, and accession for each. They are free, they need no key, and they are the same source the JMM engine uses for the revenue histories on the company pages.

Two conditions come with that access. The SEC requires a declaring User-Agent header identifying who you are and how to reach you, and it enforces a request rate. Both are trivially easy to honour and the alternative is being blocked, which is a self-inflicted outage rather than a rate-limit problem. Send a real identifier, stay inside the published rate, and cache aggressively: filing data changes when a filing arrives, not when you refresh.