Dataset catalogue | Finbar Docs

Before querying financial values, read the company's dataset catalogue. It provides the metric IDs, reporting groups and company scopes accepted by a query. If these terms are new, start with metrics, series and scopes.

Both endpoints require datasets:read. Use an access token as ACCESS_TOKEN and a company ID as ENTITY_ID.

Get the current dataset

GET /v1/entities/{entity_id}/dataset

curl --fail-with-body --silent --show-error \
  "https://api.finbar.com/v1/entities/$ENTITY_ID/dataset" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

The response contains entity_id, name, dataset_id and created_timestamp. Save dataset_id as DATASET_ID. It identifies the published version you are about to query. If no published dataset is available to your account, the request returns 404.

Read the catalogue

GET /v1/entities/{entity_id}/dataset/catalogue

curl --fail-with-body --silent --show-error --get \
  "https://api.finbar.com/v1/entities/$ENTITY_ID/dataset/catalogue" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "expected_dataset_id=$DATASET_ID" \
  --data-urlencode 'limit=25'

Query parameter	Meaning
`expected_dataset_id`	Optional check that the current publication is still the version you discovered
`limit`	Series per page, from 1 to 100; default 25
`cursor`	Continuation value from the preceding response's `next_cursor`

GET /v1/entities/{entity_id}/dataset/catalogue — 200 response

Example response. IDs and values are illustrative.

{
  "entity_id": "O-11111111111111111111111111111111",
  "name": "Example Company",
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "created_timestamp": "2026-01-15T10:00:00Z",
  "periods": [
    {
      "year": 2025,
…

Show full responseShow less

{
  "entity_id": "O-11111111111111111111111111111111",
  "name": "Example Company",
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "created_timestamp": "2026-01-15T10:00:00Z",
  "periods": [
    {
      "year": 2025,
      "end_month": 12,
      "duration_months": 12
    }
  ],
  "scope_groups": [
    {
      "scope_group_id": "consolidated",
      "name": "Consolidated",
      "description": "The company as a whole.",
      "scopes": [
        {
          "scope_id": "consolidated",
          "name": "Consolidated",
          "description": "The company as a whole.",
          "role": "explicit",
          "aliases": [
            "Group"
          ],
          "active_start": {
            "year": 2020,
            "end_month": 12,
            "duration_months": 0
          },
          "active_end": {
            "year": 2025,
            "end_month": 12,
            "duration_months": 0
          }
        }
      ]
    }
  ],
  "groups": [
    {
      "reporting_group_id": "income_statement",
      "name": "Income statement",
      "description": "Statutory income statement metrics.",
      "basis": "statutory",
      "cadence": "quarterly",
      "series": [
        {
          "series_id": "revenue.consolidated",
          "reporting_group_id": "income_statement",
          "metric_id": "income_statement.revenue.root",
          "label": "Revenue",
          "description": "Revenue for the reporting period.",
          "basis": "statutory",
          "scopes": [
            {
              "scope_group_id": "consolidated",
              "scope_id": "consolidated"
            }
          ],
          "number_format": "#,##0.0",
          "period_meaning": "span"
        }
      ]
    }
  ],
  "next_cursor": "opaque-next-page-cursor"
}

Choose a series

Response field	What to look for
`scope_groups`	Names and descriptions of the available company scopes
`groups`	Reporting groups, each with its basis, cadence and series
`groups[].series`	Metrics, descriptions and complete scope paths to select
`periods`	Historical fiscal periods found anywhere in the dataset

For each series you need, save its metric_id, reporting_group_id and complete scopes array. Check the label, description and reporting basis so that, for example, you do not select segment revenue when you need total company revenue.

The shared periods list describes dataset-wide availability. It does not promise that every selected series has a value for every period.

Read the remaining pages

If next_cursor is present, repeat the catalogue request with that value as cursor, keeping expected_dataset_id. Pagination counts series, so the same reporting group may appear across several pages. Stop when next_cursor is absent.

A 409 error with code dataset_changed means a new dataset was published during discovery. Fetch the metadata and catalogue again before querying.

Continue with dataset queries to retrieve the selected values.