Values and sources
Interpret query results, restatements and references to the original reports.
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 or MCP workflows.