For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Paddle Docs home

List meters

Returns a paginated list of meters.

Join usage-based billing early access (beta)

Usage-based billing is in early access (beta). Read how it works, then apply to join. We'll reach out if you meet the program requirements.

GET/meters

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.

Requires meter.read permission.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
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_pageinteger
Default: 50

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
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

statusarray
Default: active
Return entities that match the specified status. Use a comma-separated list to specify multiple status values.
Values
  • 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.

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
idstringrequired
Example: mtr_01kvqjfc6eb9kzk7s2wvz2aamq
Unique Paddle ID for this meter entity, prefixed with mtr_.
Pattern: ^mtr_[a-z\d]{26}$
usage_balance_unit_idstringrequired
Example: ubu_01kw8ta2j8x5t7q4v9m1kd6phz
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}$
namestringrequired
Name of this meter, shown in the Paddle dashboard.
Length: 1–255
Pattern: .*\S.*
actionstringrequired
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_]*$
descriptionstring | nullrequired
Short description for this meter.
Max length: 2048
aggregationstringrequired
Default: sum
How this meter aggregates usage events into a usage total.
Values
  • sum
    Adds up the quantity of each usage event.
unit_namestringrequired
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
ratestringrequired
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]))$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
custom_dataobject | nullrequired
Example: {"customer_reference_id":"abcd1234"}
Your own structured key-value data.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (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_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

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
{
  "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
    }
  }
}

Was this page helpful?