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

# GET /meters

**List meters**

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

Returns a paginated list of meters. Use the query parameters to page through results.

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

**Required permissions:** `meter.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: `id`. (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 meter entity, prefixed with `mtr_`. (pattern: `^mtr_[a-z\d]{26}$`)
  - `usage_balance_unit_id`: string (required) — Paddle ID of the usage balance unit that this meter draws down, prefixed with `ubu_`. Can't be changed after you create the meter. (pattern: `^ubu_[a-z\d]{26}$`)
  - `name`: string (required) — Name of this meter, shown in the Paddle dashboard. (Length: 1–255; pattern: `.*\S.*`)
  - `action`: string (required) — Action that you record usage events for, like `api_call`. Paddle matches usage events to this meter using their `action`. More than one meter can have the same `action`, as long as each draws down a different usage balance unit. A usage event then draws down the customer's usage balance for each of them. (Length: 2–64; pattern: `^[a-z][a-z0-9_]*$`)
  - `description`: string | null (required) — Short description for this meter. (Max length: 2048)
  - `aggregation`: string (required) — How this meter aggregates usage events into a usage total. (default: `"sum"`)
    - `sum` — Adds up the `quantity` of each usage event.
  - `unit_name`: string (required) — Singular name of what this meter measures, like `call` or `token`. Shown alongside usage totals. Different from the usage balance unit's `unit_name`, which is the plural name of what customers hold a balance of. (Length: 1–64)
  - `rate`: string (required) — How much of the usage balance unit that one unit of usage draws down. For example, `"1"` draws down one unit of the balance for each unit of usage, and `"0.001"` draws down one unit of the balance for every 1,000 units of usage. A decimal string greater than zero, with up to 9 decimal places. (Max length: 45; pattern: `^([1-9][0-9]{0,34}(\.[0-9]{1,9})?|0\.(?:[1-9][0-9]{0,8}|0[1-9][0-9]{0,7}|00[1-9][0-9]{0,6}|000[1-9][0-9]{0,5}|0000[1-9][0-9]{0,4}|00000[1-9][0-9]{0,3}|000000[1-9][0-9]{0,2}|0000000[1-9][0-9]?|00000000[1-9]))$`)
  - `status`: string (required) — Whether this entity can be used in Paddle. (default: `"active"`)
    - `active` — Entity is active and can be used.
    - `archived` — Entity is archived, so can't be used.
  - `custom_data`: object | null (required) — Your own structured key-value data.
  - `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": "mtr_01kvqjfc6eb9kzk7s2wvz2aamq",
      "usage_balance_unit_id": "ubu_01kw8ta2j8x5t7q4v9m1kd6phz",
      "name": "API calls",
      "action": "api_call",
      "description": "Calls to the public API",
      "aggregation": "sum",
      "unit_name": "call",
      "rate": "1",
      "custom_data": null,
      "status": "active",
      "created_at": "2026-09-01T09:10:00Z",
      "updated_at": "2026-09-01T09:10:00Z"
    },
    {
      "id": "mtr_01kvqjg1p8t8vjx4h9wq0mfz3c",
      "usage_balance_unit_id": "ubu_01kw8tc7p4z8d5s2x6n3lf8rkb",
      "name": "AI tokens",
      "action": "ai_token",
      "description": null,
      "aggregation": "sum",
      "unit_name": "token",
      "rate": "1",
      "custom_data": null,
      "status": "active",
      "created_at": "2026-09-01T09:12:00Z",
      "updated_at": "2026-09-01T09:12:00Z"
    }
  ],
  "meta": {
    "request_id": "bb093d50-ddb5-401a-a5ba-034b187b396e",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/meters?after=mtr_01kvqjg1p8t8vjx4h9wq0mfz3c",
      "has_more": false,
      "estimated_total": 2
    }
  }
}
```