> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# GET /usage-balance-units

**List usage balance units**

> **Early access (beta): usage-based billing**

Returns a paginated list of usage balance units. Use the query parameters to page through results.

By default, Paddle returns usage balance units that are `active`. Use the `status` query parameter to return usage balance units that are archived.

**Required permissions:** `usage_balance_unit.read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | array | optional | Return only the IDs specified. Use a comma-separated list to get multiple entities. |
| `after` | string | optional | Return entities after the specified Paddle ID when working with paginated endpoints. Used in the `meta.pagination.next` URL in responses for list operations. |
| `per_page` | integer | optional | Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check `meta.pagination.per_page` in the response to see how many were returned.

Default: `50`; Maximum: `200`. (Max: 200; default: `50`) |
| `order_by` | string | optional | Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.

Valid fields for ordering: `created_at`, `id`, `name`, `status`, and `updated_at`. (default: `"id[DESC]"`) |
| `status` | array | optional | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. (default: `["active"]`) |

Values for `status`:

- `active` — Return entities where the status is `active`. Returned entities can be used in Paddle and are returned when listing entities.
- `archived` — Return entities where the status is `archived`. Returned entities can't be used for billing and aren't returned when listing entities.

## Response (200)

- `data`: array (required)
  - `id`: string (required) — Unique Paddle ID for this usage balance unit entity, prefixed with `ubu_`. (pattern: `^ubu_[a-z\d]{26}$`)
  - `name`: string (required) — Name of this usage balance unit, like `API calls`. Typically short and describes what customers hold a balance of. (Length: 1–500)
  - `unit_name`: string (required) — Plural name of what customers hold a balance of, like `calls` or `credits`. Different from a meter's `unit_name`, which is the singular name of what the meter measures. (Length: 1–500)
  - `status`: string (required) — Whether this entity can be used in Paddle.
    - `active` — Entity is active and can be used.
    - `archived` — Entity is archived, so can't be used.
  - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
  - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (uri) (required) — URL containing the query parameters of the original request, along with the `after` parameter that marks the starting point of the next page. Always returned, even if `has_more` is `false`.
    - `has_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns `100001` to indicate that more than 100,000 entities match. Returns `-1` when counting is skipped or couldn't be calculated.

Use `has_more` and `next` to page through all results rather than relying on `estimated_total` for an exact count.

### Response example

```json
{
  "data": [
    {
      "id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
      "name": "API calls",
      "unit_name": "calls",
      "status": "active",
      "created_at": "2026-09-01T09:00:00.000Z",
      "updated_at": "2026-09-01T09:00:00.000Z"
    },
    {
      "id": "ubu_01kw8tc7p4z8d5s2x6n3lf8rkb",
      "name": "AI tokens",
      "unit_name": "tokens",
      "status": "active",
      "created_at": "2026-09-01T09:02:00.000Z",
      "updated_at": "2026-09-01T09:02:00.000Z"
    }
  ],
  "meta": {
    "request_id": "d8f286a6-e049-4a6e-8fa8-a6f145ac3ecf",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/usage-balance-units?after=ubu_01kw8tc7p4z8d5s2x6n3lf8rkb",
      "has_more": false,
      "estimated_total": 2
    }
  }
}
```