Dataset queries

POST /v1/entities/{entity_id}/dataset/query

This endpoint requires datasets:read. First read the catalogue to obtain the IDs, scope paths and periods you want. The query returns historical values for the selected series, keeping reporting groups separate.

Build the request

Save the following JSON as query.json. These are illustrative values: replace the dataset ID, metric ID, reporting group, scope path and period with values from your catalogue.

{
  "expected_dataset_id": "11111111-1111-4111-8111-111111111111",
  "metric_ids": ["income_statement.revenue.root"],
  "reporting_group_ids": ["income_statement"],
  "scope_combinations": [
    [{"scope_group_id": "consolidated", "scope_id": "consolidated"}]
  ],
  "periods": {
    "mode": "exact",
    "exact": [{"year": 2025, "end_month": 12, "duration_months": 12}]
  },
  "value_version": "original",
  "limit": 25
}

scope_combinations is an array of paths because one request can select several parts of a company. Each inner array must match a complete catalogue path in the same order. The query returns existing series matching your metric, scope and optional group selections; it does not create or combine series.

Send the query

Set ENTITY_ID to the company ID used for discovery. Use your access token as ACCESS_TOKEN:

curl --fail-with-body --silent --show-error \
  "https://api.finbar.com/v1/entities/$ENTITY_ID/dataset/query" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data-binary @query.json

Select a different period window

Replace only the periods field to use either of these alternatives. See reporting periods for fiscal-month and duration definitions.

Fiscal range

Select all available observations whose fiscal ends fall between the two endpoints, inclusive. Range endpoints use duration 0:

{
  "mode": "fiscal_range",
  "from": {"year": 2024, "end_month": 1, "duration_months": 0},
  "to": {"year": 2025, "end_month": 12, "duration_months": 0}
}

Trailing window

Select the last 24 months ending at the latest populated historical period in the matching series:

{"mode": "trailing", "months": 24}

Both modes can return multiple durations, including quarterly and year-to-date values. To request only annual values, use exact with the annual periods from the catalogue.

Read the response

POST /v1/entities/{entity_id}/dataset/query — 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,
…

{
  "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
    }
  ],
  "series": [
    {
      "series_id": "revenue.consolidated",
      "reporting_group_id": "income_statement",
      "metric_id": "income_statement.revenue.root",
      "label": "Revenue",
      "basis": "statutory",
      "scopes": [
        {
          "scope_group_id": "consolidated",
          "scope_id": "consolidated"
        }
      ],
      "number_format": "#,##0.0",
      "period_meaning": "span",
      "values": [
        {
          "number": 1234.5,
          "text": "1,234.5",
          "number_format": "#,##0.0",
          "fill_type": "as_reported",
          "value_version": "original",
          "report_period": {
            "year": 2025,
            "end_month": 12,
            "duration_months": 0
          },
          "sources": [
            {
              "item_id": "T-example",
              "row_index": 0,
              "column_index": 0
            }
          ]
        }
      ]
    }
  ],
  "next_cursor": "opaque-next-page-cursor"
}

Each entry in series identifies the metric, reporting group and scopes. Its values array aligns by position with the response's periods array. A missing observation is null; a reported zero is a value object with number: 0.

See values and sources before displaying or calculating with the result. That page explains stored scale, restatements and source references.

Continue or refresh

For another page, add the returned next_cursor as cursor in query.json and send the same query. Keep the selections and expected_dataset_id unchanged. Stop when next_cursor is absent.