Skip to main content
GET
List customer usage
Use a customer ID in the path to scope results to one customer, or use the wildcard distributor-customers/- to list across all of your customers. To retrieve a past billing cycle, set the filter query parameter, for example: billing_cycle == '2026-04'. There’s no lookback limit for this filter. If you omit the filter, usage defaults to the current billing cycle in UTC. See filtering for details. This endpoint also supports pagination.

Authorizations

Authorization
string
header
required

Bearer token authentication. When a distributor is registered, they receive an opaque bearer token (prefixed op_b_). Include it in the Authorization header of every request as Bearer <token>.

Path Parameters

distributor-customer
string
required

The customer ID, as defined in the distributor's own system, or the - wildcard to list usage across all of the distributor's customers.

Query Parameters

filter
string

An optional filter that limits usage to a billing cycle, using the format billing_cycle == 'YYYY-MM' (for example, billing_cycle == '2026-04'). Other filter fields aren't supported.

When omitted, usage defaults to the current billing cycle in UTC. There's no lookback limit on historical billing cycles.

max_page_size
integer<int32>

The maximum number of customer usage records to return per page. Defaults to 100 when omitted or set to 0. Values greater than 100 are clamped to 100. Negative values return an invalid_argument error.

Required range: x >= 0
page_token
string

The pagination token that identifies the page of results to return. Tokens don't expire and must be treated as opaque.

Response

A paginated list of customer usage records.

The paginated usage data for the requested customers.

results
object[]

The list of customers with their usage data for the billing cycle.

next_page_token
string

The token to use for the next page of results. Empty if there are no more results.