# Reporting periods

Distinguish fiscal years, quarters, year-to-date values and point-in-time balances.

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

Financial data is indexed by the company's **fiscal year**, the year it uses
for financial reporting. A fiscal year may end in a month other than December.
Finbar uses different period formats for document filters and dataset values.

> **How Finbar labels fiscal years**
>
> Finbar standardises reporting periods so the fiscal-year label refers to the calendar year in which the full fiscal year ends. We use this convention even when the company uses a different system, to improve comparability.
>
> For example, **1Q2026** means the first quarter of the fiscal year ending in 2026. For a company with a March year-end, this is **April–June 2025**.
>
> The only exception is a fiscal year ending in the **first half of January**, which Finbar treats as a December year-end. For example, a year ending on January 5, 2026 is labelled fiscal year 2025.

## Document periods

Document filters use compact strings such as `2025Y` for fiscal year 2025 or
`2025Q2` for its second quarter. `start_period` and `end_period` are inclusive:
both boundary periods are included.

These filters refer to the period a report covers. They do not filter by the
date the company published the report. Document results include `period`,
`report_date`, and `publish_date` as separate fields.

## Dataset periods

Dataset periods specify the fiscal year, the ending month within that fiscal
year, and the number of months covered:

```json
{"year": 2025, "end_month": 12, "duration_months": 12}
```

| Field             | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `year`            | The fiscal-year label                                            |
| `end_month`       | Month 1–12 within that fiscal year; 12 means the fiscal year-end |
| `duration_months` | Length of the interval; 0 means a value at a point in time       |

For a company whose fiscal year ends in September, `end_month: 12` still means
its fiscal year-end, not December. Use returned periods rather than converting
calendar dates into these fields yourself.

### Different values at the same fiscal month

| Example                           | `end_month` | `duration_months` | What it measures                       |
| --------------------------------- | ----------- | ----------------- | -------------------------------------- |
| Second-quarter revenue            | 6           | 3                 | Revenue earned in fiscal months 4–6    |
| First-half revenue                | 6           | 6                 | Revenue earned in fiscal months 1–6    |
| Cash at the end of the first half | 6           | 0                 | A balance at the end of fiscal month 6 |
| Full-year revenue                 | 12          | 12                | Revenue earned over the fiscal year    |

The duration cannot exceed `end_month`. A quarter, a year-to-date value and
a point-in-time balance are separate observations even when they end in the
same month.

## Choosing periods for a query

| Mode           | Use it when                                                       | Behavior                                                                                    |
| -------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `exact`        | You need specific annual, quarterly or point-in-time observations | Selects the complete period objects you supply, including duration                          |
| `fiscal_range` | You need all available observations between two fiscal month ends | Includes both ends and every available duration; use duration 0 on the range endpoints      |
| `trailing`     | You need recent history from the selected series                  | Selects a window of months ending at the latest populated historical period in those series |

A trailing window selects existing observations; it does not calculate a
trailing-twelve-month total. Range and trailing selections may include both
quarterly and year-to-date observations. Use `exact` when you need a particular
duration.

Exact selections accept up to 120 period objects. Range and trailing selections
are limited to 120 months. See [query examples](https://docs.finbar.com/api-mcp/dataset-query.md) for the
request format.

## Availability and gaps

The catalogue's `periods` array lists all historical periods found anywhere in
the dataset. The same list appears on every catalogue page. A particular series
may have no value for some of those periods; its query result will contain
`null` at those positions.

See [values and sources](https://docs.finbar.com/api-mcp/values.md) for how returned periods line up with
values.