---
title: "List the past periods of a budget"
method: GET
path: "/v1/budgets/{id}/periods"
tags: ["Budget"]
---

# List the past periods of a budget

`GET /v1/budgets/{id}/periods`

## Request

- Base URL: `https://api.cardda.com`
- URL: `https://api.cardda.com/v1/budgets/{id}/periods`
- Auth: HTTP bearer

The closed periods of a renewing budget, newest first (not paginated). The period in
progress is the budget's own `current_period`. A budget that never renewed returns an
empty list.

Readable by whoever can read the budget. A budget outside the caller's scope returns
`404 Not Found`.

## Path parameters

- `id` string, uuid, required

## Parameters

- `#/paths/~1v1~1bills/get/parameters/0` (unresolved $ref)

## Response `200`

The budget's closed periods.

- BudgetPeriod[]
  - `id` string, uuid, required
  - `scheduled_starts_on` string, date, required: The boundary (America/Santiago) the period belonged to.
  - `starts_at` string, date-time, required: When it actually started; later than `scheduled_starts_on` if it renewed late.
  - `ends_on` string, date, nullable: Scheduled renewal boundary: the day (America/Santiago) the next period was due to start. Not a spending cutoff: if the renewal ran late (`renewed_late` on the next period) the period stayed usable past this date. Its spend window is [`starts_at`, `closed_at`).
  - `closed_at` string, date-time, required: When it actually closed (the renewal ran, or the budget closed); spend up to this instant counts in it.
  - `base_amount_cents` integer, required: What the period started with.
  - `allocated_amount_cents` integer, nullable: What it ended with, top-ups and withdrawals included.
  - `spent_cents` integer: Net spend of the period (refunds subtracted).
  - `renewed_late` boolean: It started after its boundary, because its renewal was blocked (see the budget's `renewal_blocked_since`).

## Other responses

- `401`: Unauthorized - missing or invalid authentication token.
- `404`: Budget not found (or outside the caller's scope).

---

[API](https://skmtc.dev/cardda/apis/finance-api.md) - [All operations](https://skmtc.dev/cardda/apis/finance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cardda/apis/finance-api/revisions/59752c65ea74?raw)