Account and balance

Read-only endpoints describing the authenticated account, its plan and its token balance. Use them to show remaining credit in your own dashboards or to alert before a batch job runs dry.

Token amounts are returned as decimal strings because balances can exceed JavaScript's safe integer range.

Get account#

{
  "object": "account",
  "id": "8f0f1d2a-...",
  "email": "dev@example.com",
  "name": "Dev",
  "email_verified": true,
  "auth_method": "api_key",
  "plan": {
    "id": "pro",
    "name": "Pro",
    "price_usd": "40.00",
    "monthly_token_allowance": "26000000",
    "requests_per_minute": 300,
    "tokens_per_minute": 1000000,
    "max_concurrent": 10,
    "max_api_keys": 20,
    "max_context_tokens": 256000,
    "model_access": ["*"],
    "current_period_end": "2026-10-01T00:00:00.000Z"
  },
  "balance": {
    "available_tokens": "27540120",
    "purchased_tokens": "5000000",
    "subscription_tokens": "22540120",
    "reserved_tokens": "0",
    "lifetime_used_tokens": "112459880"
  }
}

plan.model_accessstring[]

Model slugs the plan may call; ["*"] means every public model.

plan.current_period_endstring | null

When the current subscription period (and its token allowance) resets. null when the account is not on a paid plan.

balance.available_tokensstring

Tokens you can spend right now: purchased plus subscription, minus reservations for in-flight requests.

balance.reserved_tokensstring

Tokens temporarily held for requests that are still running. Released or settled when each request finishes.

Get balance#

A lighter call for polling. Includes the current token-to-USD rate so you can display balances in either unit.

{
  "object": "balance",
  "available_tokens": "27540120",
  "purchased_tokens": "5000000",
  "subscription_tokens": "22540120",
  "reserved_tokens": "0",
  "approx_value_usd": "55.08",
  "token_rate": { "micro_usd_per_token": 2, "tokens_per_usd": 500000 }
}

List ledger entries#

Every credit and debit on your account, newest first. Paginate by passing the created_at of the last entry as before.

limitintegerdefault: 50

Entries per page, up to 200.

beforestring

ISO-8601 timestamp; returns entries created strictly before it.

{
  "object": "list",
  "data": [
    {
      "id": "b3c2...",
      "type": "usage_debit",
      "bucket": "subscription",
      "token_amount": "-102",
      "amount_usd": "-0.000204",
      "balance_after": "27540120",
      "description": "claud-5.1 chat completion",
      "reference": { "type": "usage", "id": "req_01J9X3..." },
      "created_at": "2026-09-15T17:39:33.071Z"
    }
  ],
  "has_more": true
}

Entry type values are credit_purchase, credit_grant (subscription allowances and bonuses), promotional_credit, usage_debit, refund, expired_credit and admin_adjustment. bucket is purchased or subscription.

Examples#

curl https://api.claudkey.com/v1/billing/balance \
  -H "Authorization: Bearer $CLAUD_API_KEY"