# XBRL us-gaap tag missing in the 10-K download

## TL;DR
A missing us-gaap tag usually means the company reported the metric under a custom extension tag instead of the standard one, not that the metric is absent. Map the extension tag through the filing's label linkbase to find the company's name for it, or sidestep the tag hunt with the SEC's companyfacts API, which carries both standard and company-specific facts. When comparing across companies, normalize each filer's custom tag to your own canonical metric.

## The error
```text
(missing data, no exception)
us-gaap tag [e.g. Revenues] not found in 10-K instance; metric absent from parsed facts
```

## When this helps
- a standard us-gaap tag is missing from a parsed 10-K
- revenue or other metrics vanish for specific companies
- building cross-company comparable financials
- validating metric coverage across a filing batch

## When it doesn't
- the company genuinely does not disclose the metric; no tag hunt creates data
- you need the metric for a pre-XBRL filing; it was never tagged
- the instance failed to parse at all; fix the parse before hunting tags

## Works with
python 3.8+ with re/json; data.sec.gov companyfacts API as of 2026. Tag availability varies by filer.

## Steps
### 1. Search the instance for extension-tagged cousins of the metric
```python
import re
xml = open("instance.xml").read()
custom = set(re.findall(r"([a-z]+:[A-Za-z]+Revenue[A-Za-z]*)", xml))
print("revenue-like tags found:", sorted(custom)[:10])
```
Expected: Candidate tags including extension ones. Companies rename revenue constantly; the standard tag is only one possibility.

### 2. Read the label linkbase for the human name of each candidate
```bash
curl -s -A "IntelBriefingBot/1.0" "https://www.sec.gov/Archives/edgar/data/[cik]/[accession]/[cik]-2026_lab.xml" -o labels.xml -w "HTTP %{http_code}\n"
grep -o "[Rr]evenue.\{0,60\}" labels.xml | sort -u | head -10
```
Expected: Human-readable labels. The label tells you which custom tag is really revenue versus something revenue-adjacent.

### 3. Pull the same metric from the companyfacts API
```bash
curl -s -A "IntelBriefingBot/1.0" "https://data.sec.gov/api/xbrl/companyfacts/CIK[cik-padded].json" -o facts.json
python3 -c "import json; d=json.load(open("facts.json")); u=d["facts"]["us-gaap"]; print([k for k in u if "evenue" in k][:10])"
```
Expected: The API's tag list for the company. It shows every tag the company actually filed, standard and custom, with values and periods.

### 4. Normalize the filer tag to your canonical metric
```python
import json
mapping = {"[cik]-2026:TotalNetRevenues": "revenue", "us-gaap:Revenues": "revenue"}
open("tagmap_[ticker].json", "w").write(json.dumps(mapping, indent=2))
print("pinned mapping:", mapping)
```
Expected: A per-company tag map. Cross-company comparison works on your canonical names, never on raw filer tags.

## Other ways people phrase this
### us-gaap revenues tag missing 10-k
The classic case. Revenue has the most custom-tag variation of any metric.

### xbrl tag not found filer extension
General form. The label linkbase is the Rosetta stone for extension tags.

### companyfacts api missing metric
If the API lacks it too, the company did not file the metric in XBRL at all.

## Why it happens
US-GAAP defines standard tags, but filers can and do create extension tags for metrics they describe differently, and some standard tags are optional. A parser looking only for the standard tag misses the custom one sitting right next to it. The data is in the filing; it is just labeled in the company's own dialect.

## Edge cases
- Two extension tags can look like revenue while only one is; the label and the calculation linkbase disambiguate.
- Tag mappings drift year to year as filers rename extensions; re-derive the map per filing.
- The companyfacts API normalizes periods but not tag semantics; the mapping step is still yours.
- Financial companies use industry tags that differ from the standard set; expect more custom tags there.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_nxDMF08ZMSQEkMwarTjQEQ
