Fundamental datasets

A dataset is a company's published financial model. It contains historical values, reporting periods and source references. This interface supports reading data; it does not edit models or download workbooks.

For an assistant, try:

Use Finbar to find Apple's financial dataset. Show the available revenue series, then retrieve annual revenue for the last three fiscal years with source references.

For the API, use a token with datasets:read permission. Reading the referenced source documents also requires documents:read. See the API quickstart for the full permission names.

1. Discover what is available

First find the company and copy its entity_id. Then read the dataset metadata and catalogue:

API requests use https://api.finbar.com with an Authorization: Bearer … header. MCP tools take entity_id as an argument.

Save the metadata's dataset_id. The catalogue lists the available metrics, reporting groups, scope paths and periods. A scope path identifies the part of the company a series covers, such as the whole company, a segment or a region. Copy the complete path from the catalogue; it may include several levels.

Use the returned identifiers rather than guessing them. Available metrics and reporting structures vary by company. Follow next_cursor to read further catalogue pages.

2. Query values

Send a JSON body to POST /v1/entities/{entity_id}/dataset/query, with Content-Type: application/json. This example selects one annual observation. Replace the example dataset ID, metric ID, scope path and period with values from your discovery results:

{
  "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 these fields plus entity_id to query_dataset.

Periods describe fiscal intervals. end_month is a month within the company's fiscal year; duration_months distinguishes an annual value from a quarter or year-to-date value. A duration of 0 represents a value at a point in time. Use the catalogue's periods rather than assuming calendar dates.

Instead of exact periods, {"mode":"trailing","months":24} selects a trailing window ending at the latest populated historical period in the selected series.

3. Read the result

The response has a shared periods array. Each entry in series has a values array in the same order.

• null means no value is available; it is different from a reported zero.
• Values retain their stored scale. Check the accompanying number format before displaying or converting them.
• Reporting groups remain separate. Finbar does not combine them or choose one on your behalf.
• Values include source references where available and identify derived values.

The default value_version is original. Use latest_restated to select the latest available restatement, falling back to the original when there is none.

Keep related requests consistent

Pass expected_dataset_id when reading the catalogue and querying values. If the published dataset changes, the API returns 409 with dataset_changed; MCP returns the same error code. Discover the dataset again and rebuild the query.

For another results page, repeat the same query with cursor set to the returned next_cursor. Stop when it is absent. An older dataset cannot be selected through this interface.