Skip to main content
GET
/
api
/
v2
/
external-billing
/
usage
Get Usage
curl --request GET \
  --url https://api.voiceaiwrapper.app/api/v2/external-billing/usage \
  --header 'Authorization: Bearer <token>'
{
  "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
  }
}
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=<ID>
GET /api/v2/external-billing/usage?client_id=<ID>&page=2&page_size=50
GET /api/v2/external-billing/usage
ParameterOptionalNotes
client_idYesScope to a single client. Omit to return all clients.
pageYesDefaults to 1.
page_sizeYesDefaults to 20, max 100.

​
Understanding the usage fields

FieldWhat it means
minutes_included_limitThe total included minutes granted by the client’s current plan for this billing period. Resets at period end.
minutes_included_usedIncluded minutes consumed so far in the current period.
minutes_addon_balanceRemaining balance of add-on pack minutes. Does not reset at period end - carries forward until exhausted.
minutes_billable_usedMinutes 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.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
client_id
string

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.

Example:

"Q2xpZW50OjEyMw=="

​
page
integer
default:1

Page number. Default: 1.

Example:

1

​
page_size
integer
default:20

Results per page. Default: 20. Maximum: 100.

Required range: x <= 100
Example:

20

Response

Usage records returned successfully.

​
data
object[]
​
meta
object