GET /v1/balance


Call	`GET /v1/balance`
Price	free
Scope	`account:read`
Operation id	`getBalance`

What it does

Cash and test balances in US dollars. Billed calls also return balance_usd, so you rarely need this. Free. Scope: account:read.

Example request

Copy it as curl. Set VERDICT_API_KEY first; uuidgen makes a fresh Idempotency-Key.

curl -X GET 'https://api.askverdict.io/v1/balance' \
  -H "Authorization: Bearer $VERDICT_API_KEY"

Example response

200: The balances.

{
  "balance_usd": 18.32,
  "test_balance_usd": 5,
  "auto_topup": {
    "enabled": false,
    "threshold_usd": null,
    "pack_usd": null
  },
  "as_of": "2026-11-07T14:03:01Z"
}

Parameters

Name	In	Type	Required	Description
`x-verdict-version`	header	string	no	API version to use, a date. Defaults to the version current when the key was created. The current version is `2026-11-01`.

Response fields (200)

Schema BalanceResponse.

Field	Type	Required	Description
`balance_usd`	number	yes	Cash balance (live keys). US dollars, up to 6 decimals.
`test_balance_usd`	number	yes	Non-cash test balance (test keys). US dollars, up to 6 decimals.
`auto_topup`	object	yes	Auto top-up settings (optional, phase 2).
`auto_topup.enabled`	boolean	yes	Whether auto top-up is on.
`auto_topup.threshold_usd`	number or null	yes	Balance that triggers a top-up. US dollars, up to 6 decimals.
`auto_topup.pack_usd`	enum: 20 or enum: 50 or enum: 200 or null	yes	Pack bought on trigger.
`as_of`	string (date-time)	yes	When the balance was read.

Errors

Errors are RFC 9457 problem details and are never billed. Branch on type. See Errors.

Status	Meaning
`400`	Invalid request: malformed JSON, an unknown field, a failed constraint or a size limit (`invalid_request`).
`401`	Missing, malformed, revoked or expired API key, or a bad webhook signature (`unauthorized`).
`403`	The key lacks the scope this operation needs (`forbidden_scope`).
`429`	Rate limited (`rate_limited`). Wait `Retry-After` seconds.
`500`	Unexpected server error (`internal`). Not billed; retry with the same `Idempotency-Key`.

Try it

Open the interactive reference to send this request from the browser. The full document is at /openapi.json.