Metrics

GET /v1/companies/{id}/metrics

Five headline figures for a company, newest period first. They come from the SEC’s Company Facts file, which holds every XBRL figure a company has filed, and arrive the morning after the SEC publishes it.

curl -H "X-API-Key: $BELFORT_API_KEY" \
  "https://belfort-data-api.vercel.app/v1/companies/AAPL/metrics?metric=net_income&frequency=quarterly"

Parameters

Parameter	Values	Default
metric	revenue, net_income, diluted_eps, operating_cash_flow, cash_and_equivalents	All five
frequency	annual, quarterly	Both

Any other query parameter gets a 400. This route doesn’t page: you get the whole series.

One figure

Field	Meaning
metric, frequency	Which series the figure belongs to.
value	The figure.
currency	Its currency, such as USD, or null.
period_end	The last day of the period, as filed.
start	The first day of the period. null for a balance, such as cash, or when the filing gave no start.
fiscal_year, fiscal_quarter	The fiscal labels, when stated. They can be null or wrong, so prefer period_end.
concept	The XBRL tag the figure was filed under, such as a revenue tag or a cash tag with or without restricted cash.
derived	true for a quarter we computed from two filed figures.
source	The filing the figure comes from: accession, filing_url, form and filed. null on a derived quarter.
first_reported	The first filing to report this exact period under this tag and unit, with the value it reported. Equal to source and value when the figure was never restated. null on a derived quarter.
operands	On a derived quarter, the two filed figures it was computed from. null otherwise.
adjustments	What we did beyond copying one filed figure. Usually empty.

Derived quarters

Companies often file a fourth quarter only inside the full year. When that happens we compute it: the year’s figure minus the nine months to date, for example. A derived quarter has derived: true, no source and no first_reported, and its operands list both filed figures, each with its filing:

• role: minuend (the longer period) or subtrahend (the part taken away).
• accession, filing_url, form, filed: the filing each figure came from.
• start, end, value: the period and the figure.

The derived figure is the minuend minus the subtrahend. Its start is the day after the subtrahend ends.

Which filing is source

source is usually the newest filing to state the figure within its frequency. It isn’t always the newest overall, because annual and quarterly series each look only at their own filings. Forms that can carry another company’s figures, such as an 8-K, an S-4 or a merger proxy, aren’t used as a source when the company’s own filing for that period exists.

Adjustments

Each adjustment has a kind and a value. What value holds depends on the kind.

kind	What happened	value holds
scale_corrected_from	Filings of this figure differ by a factor of a thousand or a million, and another filing’s figure was taken. A real 1-for-1000 split can look the same.	The figure replaced.
scale_dispute_resolved	Another filing states this figure a thousand or a million times larger or smaller, and the evidence backs this one. first_reported can then show the mis-scaled figure, because that’s what the first filing said.	The other filing’s figure.
negative_replaced_from	The tag held a negative sub-line for this period, such as intersegment sales, so the point holds the listed total.	The figure replaced.
negative_kept	The figure is negative and was kept, because it’s the company’s own total.	total_over:<tag> or no_listed_figure.
source_replaced_from	The newest filing was a form that can carry another company’s figures, so the company’s own filing was used.	The accession passed over.
cash_aligned_from	The annual and quarterly series disagreed on one balance under one tag; the point holds the newest figure a periodic filing’s balance sheet shows for that date.	The figure replaced.
cash_measure	The figure includes restricted cash, because the company tags no cash figure without it for this date.	includes_restricted.
balance_sheet_cash_over	A figure including restricted cash was also filed for this date; the point takes the cash and cash equivalents figure without it.	The tag passed over.
zero_replaced_from	A filed zero was replaced by a figure from another tag.	That tag.
stitched_under	This period came from an older tag, filed under the series’ main tag.	The main tag.
revenue_total_over	The series uses a larger total instead of a tag that looked like a sub-line. On every point of the series.	The tag passed over.
fallback_measure	The series uses a different measure, because no listed tag covers it. On every point of the series.	The measure’s tag.
fallback_promoted_over	The listed tags stopped being filed. On every point of the series.	Their last period end.
ladder_stitched	Older tags filled in periods.	tag:count, comma separated.
ambiguous_overlap	Other tags reported periods this series covers, and this series’ figure was kept.	tag:count, comma separated.
ignored_currency	The company also reported this tag in another unit, such as a convenience translation.	The units.

What to expect

• Figures can change or disappear. A later filing can restate a figure, or settle or reopen a disagreement between filings. The API serves the current reading only, with no way to ask for an earlier one. Quote meta.as_of with any figure.
• Some figures are withheld. When the rules can’t settle a figure, it’s left out of the series rather than guessed.
• Banks’ revenue is often total interest income, because many banks print no total revenue line. If you want net revenue including noninterest income, read the statements.
• A change of reporting currency drops the periods in the old currency from the series.

The measured error rates for these figures, and the cases the rules can’t see, are on Quality and Known limits.