Skip to navigation

Get usage

Returns the use of a billing period, the current one by default: minutes and SMS (included in the plan, used, left, top-ups and debt), the limit of concurrent calls and the calls rejected before an agent answered, by reason. Only quantities are returned, never amounts of money. To read a past period pass its start as period_start; the last periods are listed in available_periods. For a past period remaining, credits, debt, credit_packs, welcome and overage_billing are null, and the included amounts are those of today’s plan. Billing periods start on the anchor day of the organization, they are not calendar months. Required scope: usage:read. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:

Query parameters

period_startstringOptionalformat: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$"

First day (UTC) of a past billing period, YYYY-MM-DD, to read that period instead of the current one. Only the starts listed in available_periods of the response are valid. Omit it for the current period.

Response

Successful response.
object"usage"

Always usage.

periodobject
The billing period the figures refer to.
minutesobject

Minutes of the period: the amount included in the plan, what was used and what is left, with top-ups, pool, welcome minutes and pay-as-you-go minutes.

smsobject

SMS of the period: the amount included in the plan, what was used and what is left, with top-ups.

concurrent_callsobject
The limit of simultaneous calls of the plan.
missed_callsobject or null
Calls that were rejected before an agent answered, by reason, in the period.
available_periodslist of objects

The most recent past billing periods, valid values for period_start.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error