> ## Documentation Index > Fetch the complete documentation index at: https://www.1password.dev/llms.txt > Use this file to discover all available pages before exploring further. # List customer usage > Retrieve paginated product usage data for a distributor's customers. 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](/accounts-api/conventions#filtering) for details. This endpoint also supports [pagination](/accounts-api/conventions#pagination). ## OpenAPI ````yaml openapi/accounts_api.yaml GET /v1/distributor-customers/{distributor-customer}/usage openapi: 3.1.0 info: title: 1Password Accounts API for Partners version: v1 description: >- The 1Password Accounts API for Partners lets distributors provision and manage 1Password product entitlements for their customers, retrieve usage data, and list the products available to provision. Resources are grouped into entitlements, usage, and products. The conventions for authentication, pagination, and filtering apply across the whole API. contact: name: 1Password url: https://1password.com/contact-us servers: - url: https://api.1password.eu description: 1Password.eu (Europe) security: - BearerAuth: [] tags: - name: Entitlements description: >- Provision, update, cancel, and link 1Password product entitlements for a customer. x-group: Entitlements - name: Usage description: Retrieve product usage data for a distributor's customers. x-group: Usage - name: Products description: List the 1Password products a distributor can provision. x-group: Products paths: /v1/distributor-customers/{distributor-customer}/usage: get: tags: - Usage summary: List customer usage description: Retrieve paginated product usage data for a distributor's customers. operationId: listCustomerUsages parameters: - name: distributor-customer in: path description: >- The customer ID, as defined in the distributor's own system, or the `-` wildcard to list usage across all of the distributor's customers. required: true example: '-' schema: type: string - name: filter in: query description: >- 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. example: billing_cycle == '2026-09' schema: type: string - name: max_page_size in: query description: >- 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. schema: type: integer minimum: 0 format: int32 - name: page_token in: query description: >- The pagination token that identifies the page of results to return. Tokens don't expire and must be treated as opaque. schema: type: string responses: '200': description: A paginated list of customer usage records. content: application/json: schema: $ref: '#/components/schemas/distributor.v1.ListCustomerUsagesResponse' example: results: - customer_id: cust_789xyz products: - product_id: 1p-msp-us quantity: 25 unit: net_seats onepassword_account_id: op_acc_xyz456 billing_cycle: 2026-09 - customer_id: cust_456def products: - product_id: 1p-msp-us quantity: 100 unit: net_seats onepassword_account_id: op_acc_xyz789 billing_cycle: 2026-09 next_page_token: cursor_next_page_abc '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/Internal' components: schemas: distributor.v1.ListCustomerUsagesResponse: type: object properties: results: type: array items: $ref: '#/components/schemas/distributor.v1.DistributorCustomerUsage' description: The list of customers with their usage data for the billing cycle. next_page_token: type: string description: >- The token to use for the next page of results. Empty if there are no more results. additionalProperties: false description: The paginated usage data for the requested customers. distributor.v1.DistributorCustomerUsage: type: object properties: customer_id: type: string description: >- The unique identifier for the marketplace customer. This is the distributor-defined ID used when creating the customer's entitlement. products: type: array items: $ref: '#/components/schemas/distributor.v1.DistributorProductUsage' description: The list of 1Password products and their usage. billing_cycle: type: string description: >- The billing cycle for the returned usage data. Historical billing cycles have no lookback limit. additionalProperties: false description: A customer identifier paired with the customer's product usage data. x-aep-resource: singular: distributorcustomerusage Error: type: object properties: code: type: string description: Error code. example: not_found message: type: string description: Human-readable message. example: The requested resource was not found. required: - code - message description: Standard error response format. distributor.v1.DistributorProductUsage: type: object properties: product_id: type: string minLength: 1 description: The ID of the 1Password product. quantity: type: integer format: int32 description: >- The count of the product for the billing cycle. A quantity of `0` is reported explicitly. unit: type: string minLength: 1 description: >- How the quantity is calculated. Currently, the only unit is `net_seats`. Additional units may be introduced over time, so treat unrecognized values gracefully. example: net_seats onepassword_account_id: type: string minLength: 1 description: The ID of the 1Password account associated with this usage. additionalProperties: false description: A single product's usage for a customer in a billing cycle. required: - product_id - unit - onepassword_account_id x-aep-resource: singular: distributorproductusage responses: BadRequest: description: Bad Request - Invalid parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: invalid_argument message: The 'email' field must be a valid email address. Unauthenticated: description: Unauthenticated - Missing or invalid credentials. headers: WWW-Authenticate: description: The authentication scheme to use ("Bearer"). schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthenticated message: Authentication required. Please provide a valid bearer token. NotFound: description: Not Found - Resource does not exist. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: not_found message: The requested resource was not found. TooManyRequests: description: >- Too Many Requests - Limit is 1,000 requests per minute per distributor. There is no separate hourly limit. headers: Retry-After: description: How long to wait before retrying, in seconds. schema: type: string content: text/plain: schema: type: string example: Too Many Requests Internal: description: Internal Server Error. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: internal message: An internal error occurred. Please try again later. securitySchemes: BearerAuth: type: http scheme: bearer description: >- 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 `. ```` ## Related topics - [Reference for the 1Password Accounts API for Partners](/accounts-api/reference.md) - [1Password Accounts API for Partners](/accounts-api.md) - [API conventions](/accounts-api/conventions.md)