> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qobra.co/llms.txt
> Use this file to discover all available pages before exploring further.

# list_statement_periods

List how your statements are distributed, one row per period.

Returns one entry per period (`YYYY-MM`), newest first, with a per-status
breakdown of how many statements are in each stage and the sum of their payment
split by currency. Use it to answer "how are we managing our statements?" — e.g.
to see whether every past period is already closed (`CLOSED`) so attention can
move to the current one.

Only the statements you have access to are counted — the same set
`list_statements` returns.

Payments are converted into the currency named by `currency_mode` (each
statement's payment currency by default) and reported as a `{currency:
amount}` map per period and per status, never summed across currencies.

## Parameters

<Accordion title="Body" defaultOpen>
  <ParamField body="near_now" type="boolean">
    When True (default), only periods from the last 12 months (relative to
    today) are returned. When False, the full history is returned.
  </ParamField>

  <ParamField body="currency_mode" type="string">
    Which currency each total\_payment is converted into and labelled with:
    'payment' (default) — the currency the user is paid in; 'calculation' — the
    currency the plan computes in; 'company' — the company's global currency.
    The amount and its currency always agree. One of: `company`, `payment`,
    `calculation`.
  </ParamField>
</Accordion>

## Response

<Accordion title="Body" defaultOpen>
  <ResponseField name="periods" type="object[]">
    <Expandable title="object properties">
      <ResponseField name="period" type="string" />

      <ResponseField name="total_count" type="integer" />

      <ResponseField name="total_payment_by_currency" type="object" />

      <ResponseField name="by_status" type="object[]">
        <Expandable title="object properties">
          <ResponseField name="status" type="string">
            The statement reporting stage:

            * ERROR: the statement's calculation errored out and needs
              attention.

            * OPEN: created, not yet in the validation workflow.

            * VALIDATED: in the validation workflow, awaiting freeze.

            * LOCKED: frozen, not yet paid.

            * CLOSED: sent to payroll. One of: `ERROR`, `OPEN`, `VALIDATED`,
              `LOCKED`, `CLOSED`.
          </ResponseField>

          <ResponseField name="count" type="integer" />

          <ResponseField name="total_payment_by_currency" type="object" />
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>
</Accordion>