# Dataset catalogue

Discover the financial series and periods available for a company.

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

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](https://docs.finbar.com/api-mcp/datasets.md).

Both endpoints require `datasets:read`. Use an [access token](https://docs.finbar.com/api-mcp/authentication.md)
as `ACCESS_TOKEN` and a [company ID](https://docs.finbar.com/api-mcp/entities.md) as `ENTITY_ID`.

## Get the current dataset

```text
GET /v1/entities/{entity_id}/dataset
```

```bash
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

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

```bash
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.

```json
{
  "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](https://docs.finbar.com/api-mcp/dataset-query.md) to retrieve the selected
values.