# Metrics

> Five headline figures as time series, each with its source filing, its first report and every adjustment.

```text
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.

```bash
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](/quality/#metrics) and [Known limits](/known-limits/#metrics).

---
Source: https://docs.belfortagent.xyz/datasets/metrics/