---
title: "List credit usage by billing period"
method: GET
path: "/v1/credits/usage/periods"
---

# List credit usage by billing period

`GET /v1/credits/usage/periods`

## Request

- Base URL: `https://api.runbear.io`
- URL: `https://api.runbear.io/v1/credits/usage/periods`
- Auth: HTTP bearer

Retrieve the organization's credit position for each of its billing periods, newest first — the same figures `GET /v1/credits/usage` returns, one entry per period, for building period-over-period tracking on your side.

The period still open carries `isCurrent: true` and matches `GET /v1/credits/usage` exactly; starting a walk with no cursor, that is the first entry of the first page. Every entry whose period has already ended is closed and its usage figures are final.

History reaches back to the organization's first recorded day of credit usage — there is no fixed retention cutoff, so the number of periods available grows with the age of the account. Pass `cursor` to page further back; `nextCursor` is `null` once the oldest recorded period has been returned.

One caveat on the allowance fields (`planIncludedCredits`, `complimentaryCredits`, `includedCredits`, `overageLimitCredits`): they reflect the organization's plan configuration as it stands *today*, not as it stood during a past period. Runbear does not snapshot plan configuration per period. `currentUsageCredits` is the field that is genuinely historical, and `overageCreditsUsed` is derived from it against today's allowance.

## Query parameters

- `limit` integer: Maximum number of billing periods to return in this page (1–24). Defaults to 12.
- `cursor` string: Opaque pagination cursor. Pass the `nextCursor` from a previous response to fetch the next page of periods (ordered newest first). Omit on the first request.

## Response `200`

Default Response

- object
  - `periods` CreditUsagePeriod[], required
    - `planIncludedCredits` number, nullable, required: Credits the plan includes each billing period, with an enterprise contract override taking precedence. `null` means unlimited.
    - `complimentaryCredits` number, required: Unexpired one-off credit grants on top of the plan. `0` when there are none.
    - `includedCredits` number, nullable, required: `planIncludedCredits + complimentaryCredits` — the base overage is measured from. `null` means unlimited.
    - `currentUsageCredits` number, required: Chargeable credits consumed so far in the current billing period.
    - `overageCreditsUsed` number, required: Chargeable credits consumed beyond `includedCredits` — usage past the included allowance, not the invoiced amount (the two can differ). Always `0` on an unlimited plan.
    - `overageLimitCredits` number, nullable, required: The overage allowance enabled for the organization. `null` when overage is off, which caps usage at `includedCredits`.
    - `periodStart` string, required: Start of the billing period the usage figures cover (ISO 8601).
    - `periodEnd` string, required: End of that period (ISO 8601), exclusive.
    - `isCurrent` boolean, required: True when this entry's own `periodStart`/`periodEnd` window contains the current instant — the period still accumulating usage, whose figures `GET /v1/credits/usage` returns. The flag is read off that window, not off the entry's position in the page: starting a walk with no cursor it is the first entry of the first page, and a cursor that resolves back inside the open period returns it flagged here too. An entry whose window has already ended is closed, and its figures are final.
  - `nextCursor` string, nullable, required: Opaque cursor for the next page, or null once the oldest recorded period has been returned. Pass it back as the `cursor` query parameter.

---

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