# Values and sources

Interpret query results, restatements and references to the original reports.

Source: <https://docs.finbar.com/api-mcp/values>

A dataset query returns a `periods` array and a `series` array. Each series has
its own `values` array. Values line up with the returned periods by position:
`values[0]` belongs to `periods[0]`, `values[1]` to `periods[1]`, and so on.
Always use the response's period order.

## Missing values and zero

| Result                             | Meaning                                                       |
| ---------------------------------- | ------------------------------------------------------------- |
| `null` in `values`                 | There is no observation for that series and period            |
| A value object with `number: 0`    | The stored numeric value is zero                              |
| A value object with `number: null` | The observation has no numeric representation; inspect `text` |

Do not replace missing observations with zero. That would change the meaning of
comparisons and calculations.

## Value fields

| Field           | Meaning                                                                   |
| --------------- | ------------------------------------------------------------------------- |
| `number`        | Numeric value, if available                                               |
| `text`          | Stored text representation                                                |
| `number_format` | Formatting information for displaying the number                          |
| `fill_type`     | How the value was populated, for example `as_reported` or a derived value |
| `value_version` | Whether this observation is original or restated                          |
| `report_period` | Period of the report associated with the selected value, when available   |
| `sources`       | References to supporting paragraphs or table cells, when available        |

Values retain the scale stored in the model. Check the metric's label and
description, number format, and source table's units before converting or
combining values. For example, a value expressed in millions must not be treated
as an amount in individual currency units. Queries do not normalize units or
aggregate series.

## Original and restated values

A **restatement** is a later revision of an earlier reported figure. For example,
a later annual report may revise the comparative revenue figure for the prior
year.

| Query option                       | Returned value                                                              |
| ---------------------------------- | --------------------------------------------------------------------------- |
| `value_version: "original"`        | The original observation; this is the default                               |
| `value_version: "latest_restated"` | The latest available populated restatement, with the original as a fallback |

Each value's `value_version` identifies which version was actually selected.
Choosing `latest_restated` does not mean every returned observation was revised.

A dataset publication and a restatement are different: `dataset_id` identifies
the published model version; `value_version` selects observations within that
model.

## Follow a source reference

A source reference contains an `item_id` for a paragraph or table. A table
reference may also contain `row_index` and `column_index`; these start at zero,
so row 0 is the first row.

| Interface | Read the referenced content         |
| --------- | ----------------------------------- |
| REST API  | `GET /v1/document-items/{item_id}`  |
| MCP       | Call `read_document` with `item_id` |

Reading the source requires `documents:read` permission as well as permission
to query datasets. An empty `sources` array means no source reference was
returned for that value. It does not by itself establish whether a value was
reported or derived; inspect `fill_type` too.

Keep source references alongside your results so you or your assistant can
check the original context. See [REST document reads](https://docs.finbar.com/api-mcp/documents.md#read-a-paragraph-or-table)
or [MCP workflows](https://docs.finbar.com/api-mcp/mcp-tools.md).