> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voiceaiwrapper.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Usage
> Retrieve minute usage records for your tenant - included minutes, add-on balance, and billable overage.
This endpoint requires a **PRO plan or above**. If your plan does not include the External Billing API, the request returns `403` with error code `external_billing_api`.
## Combining filters
All query parameters are optional and can be used together or individually:
```
GET /api/v2/external-billing/usage?client_id=
GET /api/v2/external-billing/usage?client_id=&page=2&page_size=50
GET /api/v2/external-billing/usage
```
| Parameter | Optional | Notes |
| ----------- | -------- | ----------------------------------------------------- |
| `client_id` | Yes | Scope to a single client. Omit to return all clients. |
| `page` | Yes | Defaults to `1`. |
| `page_size` | Yes | Defaults to `20`, max `100`. |
## Understanding the usage fields
| Field | What it means |
| ------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `minutes_included_limit` | The total included minutes granted by the client's current plan for this billing period. Resets at period end. |
| `minutes_included_used` | Included minutes consumed so far in the current period. |
| `minutes_addon_balance` | Remaining balance of add-on pack minutes. **Does not reset** at period end - carries forward until exhausted. |
| `minutes_billable_used` | Minutes consumed beyond both the included limit and the add-on balance. These will be billed as overage. |
## How minutes are consumed
```
Incoming call minute
→ first draws from minutes_included_limit
→ once exhausted, draws from minutes_addon_balance
→ once both exhausted, increments minutes_billable_used (overage)
```
Overage minutes result in a **Cycle - Usage** payment request at the end of the billing period if the plan has a per-minute overage rate configured.
## OpenAPI
````yaml GET /api/v2/external-billing/usage
openapi: 3.1.0
info:
title: VoiceAIWrapper API
description: >-
REST API for managing campaigns, leads, clients, web widgets, and voice
providers on VoiceAIWrapper.
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.voiceaiwrapper.app
security:
- bearerAuth: []
paths:
/api/v2/external-billing/usage:
get:
tags:
- External Billing - Usage
summary: Get Usage
description: >-
Returns a paginated list of usage records (minutes included, used,
add-on balance, and billable excess) for your tenant.
If `client_id` is provided, returns the usage record for that specific
client only. Otherwise, returns usage records for **all clients** under
your agency.
## Authentication
Requires `Authorization: Bearer `. The API key must belong to a
tenant on a **PRO plan or above**.
operationId: getUsage
parameters:
- name: client_id
in: query
required: false
description: >-
Filter usage for a specific client. Accepts a plain integer ID or a
base64 GraphQL global ID. Omit to return all clients under the
tenant.
schema:
type: string
example: Q2xpZW50OjEyMw==
- name: page
in: query
required: false
description: 'Page number. Default: `1`.'
schema:
type: integer
default: 1
example: 1
- name: page_size
in: query
required: false
description: 'Results per page. Default: `20`. Maximum: `100`.'
schema:
type: integer
default: 20
maximum: 100
example: 20
responses:
'200':
description: Usage records returned successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/UsageListResponse'
example:
data:
- client_id: '42'
client_name: Acme Corp
subscription_id: '1'
minutes_included_limit: '300.00'
minutes_included_used: '120.50'
minutes_addon_balance: '60.00'
minutes_billable_used: '0.00'
current_period_start: '2025-01-01T00:00:00'
current_period_end: '2025-02-01T00:00:00'
updated_at: '2025-01-15T10:00:00'
meta:
total: 1
page: 1
page_size: 20
'401':
description: >-
Authentication failed - `Authorization` header missing, malformed,
or API key not found / disabled.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
message: Authorization header not found
'403':
description: >-
Access denied - your current plan does not include the External
Billing API. Upgrade to PRO or above.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
message: >-
External Billing API access requires a PRO plan. Error Code:
external_billing_api
'404':
description: Client not found or does not belong to your tenant.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
message: Client not found
'500':
description: Internal server error. Contact support if this persists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorMessage'
example:
message: Internal server error
components:
schemas:
UsageListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/UsageRecord'
meta:
$ref: '#/components/schemas/PaginationMeta'
ErrorMessage:
type: object
properties:
message:
type: string
UsageRecord:
type: object
properties:
client_id:
type: string
description: ID of the client.
example: '42'
client_name:
type: string
description: Display name of the client.
example: Acme Corp
subscription_id:
type: string
description: ID of the active subscription.
example: '1'
minutes_included_limit:
type: string
description: Total included minutes for the current period (decimal string).
example: '300.00'
minutes_included_used:
type: string
description: Included minutes consumed so far this period (decimal string).
example: '120.50'
minutes_addon_balance:
type: string
description: >-
Remaining add-on pack minutes balance (decimal string). Does not
reset each period.
example: '60.00'
minutes_billable_used:
type: string
description: >-
Billable overage minutes used beyond the included limit and add-on
balance (decimal string).
example: '0.00'
current_period_start:
type: string
format: date-time
nullable: true
description: Start of the current billing period (ISO 8601).
example: '2025-01-01T00:00:00'
current_period_end:
type: string
format: date-time
nullable: true
description: End of the current billing period (ISO 8601).
example: '2025-02-01T00:00:00'
updated_at:
type: string
format: date-time
description: When the usage record was last updated (ISO 8601).
example: '2025-01-15T10:00:00'
PaginationMeta:
type: object
properties:
total:
type: integer
description: Total number of records matching the query.
example: 1
page:
type: integer
description: Current page number.
example: 1
page_size:
type: integer
description: Number of records per page.
example: 20
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````