Skip to main content
GET
Read the balance of the account associated with your API key. Authenticate with X-Api-Key and the usage.read permission, following the same authorization rules as the other billing reads. This endpoint accepts no body, account-selection, billing-period, or pagination parameters. A parent key reads its own account; use a child’s key to read that child’s balance. Account-selection query parameters do not change the account. Responses use Cache-Control: no-store.

Response Fields

integer
The authenticated account ID.
string
Always USD.
string
Remaining account credit after posted deductions, formatted with two decimal places. Includes credit added by staff and confirmed prepaid funding; excludes any overdraft allowance.
string | null
Known unpaid SMS and MMS charges priced using settlement pricing. Null when the calculation is unavailable or usage is comped.
string | null
funded_credit − known_unpaid_sms. May be negative. Null when unpaid usage cannot be calculated or usage is comped.
string
Snapshot time in ISO-8601 UTC.
string | null
null for a complete snapshot, billing_bypass for comped usage, or prepaid_billing_unavailable when the unpaid/net calculation is unavailable.
object
Separate testing allowance and debt snapshot. Always present; fields are listed below.
testingBilling contains enabled and previouslyEnabled booleans; endedAt (ISO-8601 UTC or null); limitUsd, accruedUsd, unbilledUsd, reservedFeeUsd, and exposureUsd USD decimal strings (nullable except limitUsd); sendingPaused boolean; reason string or null; and asOf ISO-8601 UTC time. Unavailable amounts are null, never assumed zero. Monetary values are decimal strings, including confirmed zero ("0.00"). An unavailable calculation is null, never an assumed zero. On an existing billing configuration, an unset credit field uses its defined zero-credit default when calculating unpaid usage and net balance. This default does not write a balance to the account. An account without a billing configuration returns 404. Funded credit must be nonnegative and an exact whole-cent amount: invalid stored amounts, including sub-cent credit such as -0.001, return 503 balance_unavailable before any rounding.

Balance Meaning and Availability

The net balance includes known unpaid SMS/MMS usage only. Provider costs still arriving and other product liabilities are excluded. Overdraft capacity is not funded credit. A positive balance does not establish permission to send: use send preflight to check eligibility. Complete net calculations support ordinary self-paying accounts, including custom usage tiers. Accounts with pooled or commercial pricing, parent-paid accounts, and accounts awaiting settlement/debit/audit reconciliation receive readable funded credit with null unpaid and net amounts. Legacy special pricing also receives this partial response. A parent-paid account never receives its parent’s credit balance. For billing-bypass accounts, usage is comped: the response shows funded credit with reason: "billing_bypass" and null unpaid/net amounts. Comped usage is never presented as debt. Reading a balance does not charge the account or change its SMS pause state. For active or previously enabled testing billing, funded_credit remains readable, while known_unpaid_sms and net_balance are null with reason: "prepaid_billing_unavailable". Read unpaid testing debt and its separate send allowance from testingBilling; do not subtract it from funded credit.

Examples

Error Codes

Other account/key policy errors follow the shared error reference.