Datasets API and MCP | Finbar Docs

A Finbar model is called a dataset in the public API. Dataset reads expose the company's active published snapshot, with historical values across reporting bases and scopes. Estimates, workbook downloads, and model editing are outside this interface.

Access

Request datasets:read for the resource you use: https://api.finbar.com for REST or https://mcp.finbar.com/mcp for MCP. Existing credentials need the new grant; existing access tokens do not gain it automatically. Reading the source documents referenced by values additionally requires documents:read.

Discover a dataset

Resolve the company with the existing entity search, then use its entity_id:

| REST operation | MCP tool | | --- | --- | | GET /v1/entities/{entity_id}/dataset | get_dataset | | GET /v1/entities/{entity_id}/dataset/catalogue | get_dataset_catalogue | | POST /v1/entities/{entity_id}/dataset/query | query_dataset |

REST requests use https://api.finbar.com and an Authorization: Bearer … header. MCP tools take entity_id in their arguments.

Metadata contains entity_id, company name, dataset_id, and created_timestamp. The timestamp identifies snapshot creation; it is not a publication date.

The catalogue groups series by reporting group, with its description, basis, and cadence. Each series includes a metric ID, label and description, full scope path, number format, period meaning, and available periods. Scope definitions include names, descriptions, aliases, roles, and available activity bounds. Use identifiers returned by this catalogue; metric and scope availability varies by company.

A scope path is ordered from the enclosing reporting scope through any nested subdivisions. For example, a consolidated series subdivided into a business segment and then a geography carries all three scope selections. Copy the complete path into a query.

Catalogue pages contain up to 25 series by default, or 100 with limit=100. Reporting groups may continue on later pages. Follow next_cursor until it is absent.

Query values

This illustrative REST body selects one metric and scope path; replace their identifiers and the dataset UUID with values from discovery. Send it to POST /v1/entities/{entity_id}/dataset/query with Content-Type: application/json:

{
  "expected_dataset_id": "11111111-1111-4111-8111-111111111111",
  "metric_ids": ["income_statement.revenue.root"],
  "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
}

For MCP, pass the same fields plus entity_id to query_dataset.

Optional reporting_group_ids restricts results to specific groups. Without it, matching statutory, company-defined, and Finbar-defined series are returned separately. Finbar does not aggregate or choose between those series.

Periods identify fiscal intervals, not calendar dates. end_month is the month within the company's fiscal year. duration_months=0 identifies a point-in-time observation. Discrete quarters, cumulative year-to-date values, and annual values remain distinct even when they share an end month.

Two other period selections are supported:

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

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

Ranges include all available durations within their fiscal end bounds. Trailing windows end at the latest populated historical period among the selected series. Requests accept up to 50 metrics, 50 scope paths, and 120 exact coordinates or months.

Responses contain a shared ordered periods array and a series array. Each series' values array aligns with those periods. A missing observation is null, while a reported zero remains zero. Exact selections retain requested coordinates even where coverage is missing. Unknown metrics, reporting groups, or scope paths return validation errors.

Each populated value includes its numeric and text content, number format, fill type, selected version, available report period, and source item references. Numbers retain their stored scale; number formats describe presentation, not a new conversion. Derived values remain identified by their fill type. Source table row and column coordinates are zero-based.

value_version defaults to original. Set latest_restated to select the final populated restatement in the dataset, falling back to the original when none exists. The returned value identifies the version actually used.

Keep multi-call reads consistent

Pass the metadata's dataset_id as expected_dataset_id when reading the catalogue and querying. If the active publication changes, REST returns HTTP 409 with error code dataset_changed; MCP returns the same code in its tool error. Refresh discovery and rebuild the query.

Cursors also bind to the active dataset and selectors. Repeat the same query with cursor set to next_cursor; the page limit may change. Query period arrays remain consistent across pages. An older snapshot cannot be selected through this interface.