> ## Documentation Index
> Fetch the complete documentation index at: https://docs.citino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Metric objects

> Every number the API returns is an object carrying its value, its ± band, how many answers it rests on, and whether a change is within noise.

A figure never leaves Citino as a bare number. Visibility, share of voice, position, sentiment, and the retrieval and citation rates on the source reports all arrive in the same shape, and there is no option to drop the band or the sample size. A number charted without them is how a chance wobble gets reported as a trend.

```ts theme={null}
interface Figure {
  value: number | null;
  unit: "percent" | "points" | "count" | "score" | "rank" | "ratio";
  band: number | null;
  n: number;
  delta: number | null;
  within_noise: boolean;
  low_sample: boolean;
  state: "measured" | "no_data" | "never_named";
  note?: string;
}
```

## Fields

**value** `number | null`

The figure, in its `unit`. A percentage is on a 0 to 100 scale, to one decimal place. `null` when there are no answers behind it yet (`n` is 0), never `0`: "not measured yet" and "measured and named in none" are different findings.

**unit** `string`

How to read `value`, `band` and `delta`. `percent` for visibility, share of voice and the source rates. `rank` for position, where 1 means named first and lower is better: print it as a place, not with a percent sign. `score` for sentiment, from 0 (negative) to 100 (positive). The other units appear on a few figures elsewhere in the API.

**band** `number | null`

The ± range, in the same unit as `value`: the true figure could reasonably be anywhere from `value - band` to `value + band`. In the app's words: "How far the true number could reasonably be from the one shown. It is wide when there are few answers or few questions behind it, and narrows as more come in." See below for when it is `null`.

**n** `integer`

How many answers the figure rests on. "How many answers a number is based on. The more answers, the more you can trust it." For position and sentiment, only the answers that named the brand count, so their `n` is usually smaller than visibility's.

**delta** `number | null`

The change since the previous period of the same length, in the figure's unit: percentage points for a percentage, never a percent of a percent. `null` when there is nothing to compare with. Report rows always carry `null`, because a row covers one bucket and has no previous one.

**within\_noise** `boolean`

`true` when the change is smaller than the band, so it could be chance. "How much this moved since the previous period of the same length, in percentage points. “Within noise” means the move is smaller than the ± range, so it could be chance." Also `true` whenever `delta` is `null`. A within-noise change is not a movement: do not colour it, arrow it, sort by it or alert on it.

**low\_sample** `boolean`

`true` when the figure rests on few answers. "This number rests on only a few answers, so read it as an early signal rather than a settled result. It firms up as we collect more each day." The value is still there; show it with a quiet mark beside it rather than hiding it. Read this flag rather than working out your own threshold: it is set where the figure is computed, and differs by metric.

**state** `string`

`measured` for an ordinary figure. `no_data` when nothing has been measured yet: `value` is `null` and `note` says why. `never_named` when a percentage is 0 with answers behind it: the brand was measured and named in none of them. That is a finding, not an error.

**note** `string`

Present only when `n` is 0, saying "needs one full run".

## When `band` is null

* **A figure over a single prompt.** The band measures how much a figure would move if the set of questions were drawn again, so it needs more than one question. On the [brands report](https://docs.citino.ai/api/reports.md) with `prompt` as a dimension, and on figures computed for one prompt (Prompt detail, for example), `band` is `null`. `n` and `low_sample` are still set.
* **Domain and URL rates.** A retrieval or citation rate is a share of answers Citino counted directly, not an estimate, so it carries no band, as on the Sources screen.
* **Not enough to compute one.** A figure with no answers behind it has no band.

A `null` band is not a zero band. Do not draw it as a certain number; show `n` beside it instead.

## Using figures well

* **Keep the band and `n` with the value**, in your warehouse and on your charts. Draw the band as a shaded range or an error bar.
* **Do not add up or average figures from different rows.** Visibility on one engine and visibility on another rest on different numbers of answers, so their average is not your overall visibility. For a total, ask for the report with fewer dimensions: a row with no dimensions is the same figure Overview shows for the window.
* **Compare like with like.** Every figure is counted over the scope the response states: the days, the engines and the claimed segments. Two figures from different scopes are different measurements.
* **In CSV**, each figure becomes four columns: the value, `_band`, `_n` and `_low_sample`. See [CSV output](https://docs.citino.ai/api/csv.md).

## Related

> [card] [The ± band and n](https://docs.citino.ai/guides/bands-and-sample-size.md)
>
> What the band and the sample size mean, for a reader.

> [card] [Within noise](https://docs.citino.ai/guides/within-noise.md)
>
> Why a small change is not news.

> [card] [How bands are computed](https://docs.citino.ai/guides/methodology/bands.md)
>
> The method behind the band.

> [card] [Reports](https://docs.citino.ai/api/reports.md)
>
> Figures by date, engine, segment and prompt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.