Tone docs
API referenceWallet

Spend by category over the selected period

Calls, numbers and adjustments, each as a single figure. A purchase and its reversal fall in the same bucket, so the numbers show what something actually cost rather than a gross figure beside a credit that cancels it.

Open in ClaudeOpen in ChatGPTView as Markdown

Requires the read scope. A key with less gets 403 insufficient_scope.

GET
/v1/wallet/usage

Authorization

AuthorizationBearer <token>

Authorization: Bearer tone_live_… or tone_test_…. The prefix IS the environment: a test key reaches only the sandbox, and no request field bridges the two.

In: header

Query Parameters

period?string

How far back to look. A closed set rather than an arbitrary window — this is a billing summary, not a reporting API. Open set — handle an unrecognised value rather than throwing. Today: 7d, 30d, all.

Default"30d"

Value in

  • "7d"
  • "30d"
  • "all"
agent_id?string

Narrow the breakdown to one agent calls.

Match^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/wallet/usage"
{  "data": {    "addedPaise": 0,    "agentId": "9f1c2d84-4e3a-4f6c-b902-7d1e8a33c451",    "categories": [      {        "category": "calls",        "entries": 0,        "spentPaise": 0      }    ],    "from": "2026-08-25T09:14:22Z",    "period": "7d",    "to": "2026-08-25T09:14:22Z",    "totalSpentPaise": 0  }}
Was this page helpful?

Wallet transactions, newest first

The ledger behind the balance, and the source of truth for it: every top-up, call, number purchase, monthly rental and compliance verdict. Append-only — a correction is a new compensating row, never an edit.

Check whether an email is available for signup

Sign-up itself answers GENERICALLY when an address is already registered, because telling callers which addresses exist is an account-enumeration oracle. This endpoint exists so the sign-up form can show an honest "already registered" message instead; it is deliberately the only place that distinction is made.