Metrics, series and scopes
How Finbar organizes a company's financial dataset.
A financial dataset is the historical data in a company's published Finbar model. It contains metrics such as revenue, the parts of the company those metrics describe, and values for different reporting periods.
Each company has an entity_id. Its current published dataset has a separate
dataset_id, which changes when a new dataset is published. A company's
catalogue lists the series and periods available in that dataset so you
can select what to query.
Metrics and series
A metric is a measure, such as revenue or operating profit. A series is that metric for a particular part of the company and reporting group, measured over time.
For example, total company revenue and a division's revenue may use the same metric, but they are different series. Similarly, statutory operating profit and a company's adjusted operating profit should remain distinct.
| Field | Meaning | How you use it |
|---|---|---|
metric_id | Identifies the measure | Select the metric to query |
series_id | Identifies one series in the dataset | Distinguish returned series |
label and description | Explain what the measure represents | Check the definition before comparing values |
reporting_group_id | Identifies the group the series belongs to | Restrict a query to the required reporting group |
scopes | Identifies the part of the company covered | Copy the complete selection into your query |
IDs and available metrics vary by company. Discover them from the catalogue; do not construct them from a metric's display name.
Reporting groups and basis
A reporting group holds related series, such as an income statement or a set of company-defined performance measures. It includes a basis, which identifies whose definitions the figures follow, and a cadence, such as quarterly, which describes the reporting frequency.
basis | Meaning |
|---|---|
statutory | Measures reported under the company's applicable accounting standards |
company_definition | Measures defined by the company, such as its own adjusted profit measure |
finbar_definition | Measures defined by Finbar |
The same metric can appear in more than one group. Queries keep those groups separate; they do not add the values together or decide which definition is appropriate for your analysis.
Company scopes
A scope says which part of the company a series covers: the whole company (often labelled “Consolidated”), a business segment, a geography, or a more specific subdivision. A scope group names the dimension; a scope is one member of that dimension.
A series's scopes array is its scope path. This illustrative path describes
the European business within a software segment:
[
{"scope_group_id": "segment", "scope_id": "software"},
{"scope_group_id": "geography", "scope_id": "europe"}
]
The actual names and IDs come from the catalogue. Copy a series's entire
scopes array, in its returned order, as one entry in scope_combinations.
Selecting only the last element does not select the same series.
Here, “scope” describes financial data. An OAuth scope, such as
datasets:read, is a permission to access that data. See
authentication for the permission names.
Dataset versions
The dataset_id identifies one fixed published version. Pass it back as
expected_dataset_id when reading the catalogue or querying values. This lets
Finbar detect a publication change between your requests, rather than letting
you use selections from an outdated catalogue.
If you receive dataset_changed, fetch the current dataset and catalogue and
rebuild the query. The interface reads the current publication; it cannot select
an older dataset by ID. created_timestamp is the dataset's creation time,
which is not necessarily its publication time.
Continue with reporting periods, or start retrieving data through REST dataset discovery or MCP tools.