# Inputs and examples

Use JSON without spreadsheet addresses or formulas. The examples below are MCP arguments. Replace the illustrative `entity_id` with one returned by `search_entity`, and choose a key for the intended run before submitting. The example values are invented.

## Rows and values

Each row needs a stable `id`, `label`, `unit` and positive `scale`. Row IDs must be unique and contain no colon. Use `description` to clarify the measure, `basis` for conventions such as GAAP or adjusted, and `scope` for consolidated versus segment figures. Preserve the user's choices.

`unit: "USD"` and `scale: 1000000` express values in millions of dollars. For ratios, specify whether 15% should be returned as 0.15 or 15; do not silently change conventions. Describe whether an ambiguous row is a balance at period-end or an amount earned/spent over the period.

Build can start with `observations: []`. Update requires at least one numeric existing observation. For user-supplied numbers, include `status: "provided"`, a numeric `value`, and `sources: []`. Preserve complete observations from earlier Finbar results: reported values need sources, derived values need calculations, and unresolved values need a null value and reason. Existing values guide matching; they are not supporting evidence for newly researched values.

`value_version` defaults to `original`, meaning the originally reported figures. Use `latest_restated` when the user wants subsequently revised figures. Optional `instructions` can clarify the requested financial definitions and reporting conventions.

## Reporting periods

Use the same object for target periods, existing observations and result filters:

```json
{"year": 2025, "period_type": "Q", "period": 2}
```

`year` is Finbar's fiscal-year label, from 1900 to 2500. It normally identifies the calendar year in which the fiscal year ends. A year ending in the first half of January is treated as ending in the preceding December. Check the company's reporting calendar when translating the user's dates.

| `period_type` | `period` | Meaning |
| --- | --- | --- |
| `Y` | 0 | Full fiscal year |
| `H` | 1–2 | First or second half-year |
| `Q` | 1–4 | Individual fiscal quarter |
| `QC` | 1–4 | Cumulative quarters from fiscal-year start; QC3 is the first nine months |
| `M` | 1–12 | Month within the fiscal year |
| `YT` | 0 | Transitional year following a fiscal year-end change |
| `QT` | 1–4 | Transitional quarter following a fiscal year-end change |

For a March year-end company, Q1 of fiscal 2026 means April–June 2025. Q2 revenue covers only the second quarter; QC2 revenue covers the first six months. Cash for either is a period-end balance, but keep the exact requested period type in the input and output. Transitional periods require the actual reporting interval to be established from sources.

Specify target periods explicitly; there is no automatic "latest" selection. Each target applies to every supplied row. Dataset monthly periods count from fiscal-year start; document search has a separate calendar-month convention.

## Build example

Call `build_dataset` to populate a supplied revenue row for fiscal 2025:

```json
{
  "idempotency_key": "example-revenue-build-2025-001",
  "dataset": {
    "entity_id": "O-11111111111111111111111111111111",
    "rows": [
      {
        "id": "revenue",
        "label": "Revenue",
        "basis": "GAAP",
        "scope": "Consolidated",
        "unit": "USD",
        "scale": 1000000
      }
    ],
    "observations": []
  },
  "target_periods": [{"year": 2025, "period_type": "Y", "period": 0}],
  "value_version": "original"
}
```

## Update example

Call `update_dataset` to research fiscal 2025 with a supplied fiscal 2024 value as context. The non-target 2024 observation is retained. To refresh 2024 itself, include that period in `target_periods`.

```json
{
  "idempotency_key": "example-revenue-update-2025-001",
  "dataset": {
    "entity_id": "O-11111111111111111111111111111111",
    "rows": [
      {
        "id": "revenue",
        "label": "Revenue",
        "basis": "GAAP",
        "scope": "Consolidated",
        "unit": "USD",
        "scale": 1000000
      }
    ],
    "observations": [
      {
        "row_id": "revenue",
        "period": {"year": 2024, "period_type": "Y", "period": 0},
        "value": 800,
        "status": "provided",
        "sources": []
      }
    ]
  },
  "target_periods": [{"year": 2025, "period_type": "Y", "period": 0}],
  "value_version": "original"
}
```

## Size limits

A request accepts up to 200 rows, 40 unique target periods, 2,000 row/period combinations, 8,000 existing observations and 2 MiB of JSON. An individual observation is limited to 8 KiB. If splitting is necessary, keep calculation dependencies together and preserve already saved results. Do not expand one requested job into many paid runs without considering the user's scope and spending constraints.

For further field details, see the available tool schema and [public dataset documentation](https://docs.finbar.com/api-mcp/build-update-datasets).