Which US-GAAP tag each field is read from, in the order they are tried. This page is generated from the mapping code on every request, so it always matches what the API does.
as_of, only values filed on or before that date are eligible.us-gaap taxonomy are read.
Company extension tags — elements a filer defines for itself — are never read,
even when one carries the number you would expect.null, and so is its provenance. Nothing is estimated.include_provenance=true, each value’s
provenance names it in tag, next to the accession, filed date and form —
so you can check it against this page, and remap it if you disagree.IFRS filers are not mapped at all: they return UNSUPPORTED_FILER (see
Accuracy & coverage).
| Field | Tags, in the order tried |
|---|---|
total_revenue | If none is reported, it may be computed instead: |
gross_profit | If none is reported, it may be computed instead: |
net_income | |
operating_income | Banks and insurers don't report an operating income line, so theirs is blank; the bulk file marks those blanks "not applicable". A few companies with no operating income line tag their segment total with this element (e.g. Disney), which leaves out corporate costs. |
pretax_income | Income from continuing operations before income taxes. The second tag is the figure before equity-method income, which some filers report instead. |
income_tax_expense | Negative is a tax benefit. |
interest_expense | SEC's 2024 taxonomy split InterestExpense into InterestExpenseNonoperating (most companies) and InterestExpenseOperating (banks and insurers), so all three are read. For a bank it is total interest expense, deposits included. A value filed as a negative number (a sign error) is shown as the positive expense, with a note in provenance. |
| Field | Tags, in the order tried |
|---|---|
total_assets | |
total_liabilities | If none is reported, it may be computed instead: |
stockholders_equity | If none is reported, it may be computed instead: |
noncontrolling_interest | If none is reported, it may be computed instead: |
total_equity | If none is reported, it may be computed instead: |
temporary_equity | If that is not reported: Temporary equity attributable to the parent and Redeemable noncontrolling interest. If only one is reported it is read directly (its tag is named); if both are, they are summed (a computed value). If none is reported, it may be computed instead: |
cash_and_equivalents | Excludes restricted cash. The cash-flow statement's total that includes it is a different figure and is not used. |
current_assets | Banks, brokers, insurers and REITs usually present an unclassified balance sheet, so they report no figure; the bulk file marks those blanks "not applicable". |
current_liabilities | Banks, brokers, insurers and REITs usually present an unclassified balance sheet, so they report no figure; the bulk file marks those blanks "not applicable". |
net_ppe | The second tag is one line that also includes finance-lease right-of-use assets, which some filers report instead. |
long_term_debt | As the balance sheet shows it: excludes the part due within a year (long_term_debt_current). Add the two for total long-term debt. It includes finance-lease obligations only when the filer reports them in one line with its debt (the second tag). Short-term borrowings are in neither. Banks, insurers and REITs show one long-term debt line with no split by due date: for a year with no current assets or current liabilities, that line (LongTermDebt) is read instead, including any part due within a year, and provenance carries a note saying so. |
long_term_debt_current | The part of long-term debt due within a year. DebtCurrent is not used: it also includes short-term borrowings. Not applicable to banks, brokers, insurers and REITs, which don't split debt by due date. |
| Field | Tags, in the order tried |
|---|---|
operating_cash_flow | |
investing_cash_flow | |
financing_cash_flow | |
depreciation_amortization | Depreciation, depletion and amortization as added back in the cash-flow statement. A filer with none of these tags gets its plain Depreciation figure (Microsoft, Alphabet, Tesla), with a note: it is depreciation only, often from the property and equipment note, so it leaves out amortization and anything else the cash-flow add-back includes (Microsoft: $34.3B vs a $38.5B cash-flow line). The last tag nets accretion, so a bank's or insurer's can be negative. |
capex | Capital expenditures, as a POSITIVE amount paid: free cash flow is operating_cash_flow - capex. A payment filed as a negative number (a sign error) is shown positive, with a note in provenance. |
buybacks | Repurchases of common stock (else of all equity), as a positive amount paid; a negative filed value is shown positive, with a note. |
dividends_paid | Dividends paid to common shareholders where reported, else the filer's total dividends paid; a positive amount, a negative filed value shown positive with a note. |
| Field | Tags, in the order tried |
|---|---|
eps_basic | In the reporting currency per share, as filed (a decimal). Like every field, the latest filed figure: after a stock split, earlier years read the split-adjusted figure from a later 10-K (if one re-reported that year); pass as_of for the figure first reported. The second tag is used when the filer reports one figure for basic and diluted. |
eps_diluted | In the reporting currency per share, as filed. Restated after a stock split like basic EPS. The second tag is used when the filer reports one figure for basic and diluted. |
diluted_shares | The weighted-average number of diluted shares for the year, the denominator of diluted EPS. Restated after a stock split like EPS; when it was (by 1.5x or more), provenance carries a note. With no diluted count but diluted EPS equal to basic EPS, the basic weighted count (WeightedAverageNumberOfSharesOutstandingBasic) is read (Exxon Mobil). A count the filer tagged in thousands or millions (or that much too large) is shown at the scale its own EPS and net income prove, with a note. |
shares_outstanding | The cover-page count from the year's annual report (dei taxonomy), dated a few weeks after the year-end and never restated, so after a later stock split it is on a different basis from EPS and diluted shares (provenance notes it). Companies with several share classes report the cover count per class, which SEC's data leaves out; for them the balance-sheet count at the year-end is read (Alphabet). Some (Meta, Ford) report neither undivided, and the field is blank. A count of 0 in a filing is a placeholder and is treated as not reported. |
A few fields are computed from other reported values when their own tags are missing. The
provenance of a computed value says so: derived is true,
tag is null (no single element holds the number) and
derivation carries the formula shown here. A name in braces, such as
{cost_of_revenue}, is an input with more than one possible tag: in
derivation it is replaced by the tag actually read. Each input’s tags, in
order, are listed below.
gross_profit
When: No GrossProfit tag is reported, but revenue and cost of revenue are.
derivation: total_revenue - {cost_of_revenue}
Reads: total_revenue, Cost of revenue
total_equity
When: No total-equity tag is reported; parent equity and noncontrolling interest are.
derivation: StockholdersEquity + MinorityInterest
total_equity
When: No total-equity tag and no noncontrolling interest are reported, so total equity equals parent equity.
derivation: StockholdersEquity (no noncontrolling interest reported)
Reads: stockholders_equity
stockholders_equity
When: StockholdersEquity is not reported; total equity and noncontrolling interest are.
derivation: StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest - MinorityInterest
Reads: total_equity, noncontrolling_interest
noncontrolling_interest
When: MinorityInterest is not reported, and total equity and parent equity differ.
derivation: StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest - StockholdersEquity
Reads: total_equity, stockholders_equity
temporary_equity
When: The total temporary-equity tag is not reported and both portions are. (If only one portion is reported, it is read directly and its tag is named.)
derivation: TemporaryEquityCarryingAmountAttributableToParent + {redeemable_nci}
Reads: Temporary equity attributable to the parent, Redeemable noncontrolling interest
total_liabilities
When: Liabilities is not reported; total liabilities and equity, and equity, are.
derivation: LiabilitiesAndStockholdersEquity - {equity_incl_nci}
Reads: Total liabilities and equity, Equity including noncontrolling interest
total_liabilities
When: As above, for a filer that also reports temporary equity, which sits between liabilities and equity and so is netted out.
derivation: LiabilitiesAndStockholdersEquity - {equity_incl_nci} - temporary_equity
Reads: Total liabilities and equity, Equity including noncontrolling interest, temporary_equity
total_revenue
When: The first revenue tag found is InterestAndDividendIncomeOperating (a bank's gross interest income) and net interest income and noninterest income are both reported for the period. This is the total net revenue banks themselves report. If either is missing, gross interest income stays, with a note in provenance.
derivation: InterestIncomeExpenseNet + NoninterestIncome
Reads: Net interest income (banks), Noninterest income (banks)
Resolved the same way as a field: tags in order, the first one reported wins.
| Input | Tags, in the order tried |
|---|---|
Cost of revenuecost_of_revenue | |
Total liabilities and equityliabilities_and_equity | |
Equity including noncontrolling interestequity_incl_nci | |
Net interest income (banks)bank_net_interest_income | |
Noninterest income (banks)bank_noninterest_income | |
Temporary equity attributable to the parentparent | |
Redeemable noncontrolling interestredeemable_nci |
The first revenue tag a company reports is sometimes a partial figure (for example about $2B under Revenues next to about $18B of total revenue). Size alone can’t tell, because some companies deliberately report a smaller net figure, so the company’s own figures for the same period decide. Revenue should equal one of these totals (within 1%): cost of revenue + gross profit, costs and expenses + operating income, operating expenses + operating income, cost of revenue + operating expenses + operating income, cost of revenue + SG&A + operating income. Only when the tag found matches none, and a later tag in the revenue list that is at least 1.5× larger matches one, is the later tag used. Some companies have operating lines outside these totals, which leaves the totals a few percent off their revenue. So when the tag found is less than 1/1.5 of every total, a later tag within 10% of one is used. That value’s provenance then carries a note saying so. The check never switches to gross interest income, and it reads these tags only for this purpose:
| Input | Tags, in the order tried |
|---|---|
Costs and expensescosts_and_expenses | |
Operating expensesoperating_expenses | |
Selling, general and administrative expensesga | |
Operating incomeoperating_income |
pretax_income has two tags: income before taxes, and the same line before income from equity-method investments. Some companies report the income statement’s line under the second and use the first for another figure, and a company that changes tags leaves an older version under the first. So when both tags report the period with different values, the company’s own figures decide: pretax income minus income_tax_expense should equal one of its after-tax figures for the period (within 1%) — net income, with or without noncontrolling interests and discontinued operations; equity-method income may sit between the two. Only when the first tag found fits none and the other fits one is the other tag used. That value’s provenance then carries a note saying so. If both or neither fit, the tag order stands. The check reads these tags only for this purpose:
| Input | Tags, in the order tried |
|---|---|
Net income including noncontrolling interestsprofit_loss | |
Income from continuing operationscontinuing_ops | |
Income from continuing operations including noncontrolling interestscontinuing_ops_incl_nci | |
Net income attributable to noncontrolling interestsnci | |
Net income attributable to redeemable noncontrolling interestsredeemable_nci | |
Income from discontinued operations, net of taxdiscontinued | |
Income from equity-method investmentsequity_method |
Open an issue
with the company, the year and the field. The tag in that value’s provenance
shows which rule applied, which makes it quick to check.