# 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

**`GET /v1/account`**

```json
{
  "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": 1000000,
    "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_access` (string[]): Model slugs the plan may call; `["*"]` means every public model.
- `plan.current_period_end` (string | null): When the current subscription period (and its token allowance) resets. `null` when the account is not on a paid plan.
- `balance.available_tokens` (string): Tokens you can spend right now: purchased plus subscription, minus reservations for in-flight requests.
- `balance.reserved_tokens` (string): Tokens temporarily held for requests that are still running. Released or settled when each request finishes.

## Get balance

**`GET /v1/billing/balance`**

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

```json
{
  "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": 0.5, "tokens_per_usd": 2000000 }
}
```

## List ledger entries

**`GET /v1/billing/ledger`**

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

- `limit` (integer, default `50`): Entries per page, up to 200.
- `before` (string): ISO-8601 timestamp; returns entries created strictly before it.

```json
{
  "object": "list",
  "data": [
    {
      "id": "b3c2...",
      "type": "usage_debit",
      "bucket": "subscription",
      "token_amount": "-102",
      "amount_usd": "-0.000204",
      "balance_after": "27540120",
      "description": "claude-opus-5-5 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**

```bash
curl https://api.claudech.com/v1/billing/balance \
  -H "Authorization: Bearer $CLAUDECH_API_KEY"
```

**JavaScript**

```javascript
const res = await fetch('https://api.claudech.com/v1/billing/balance', {
  headers: { authorization: `Bearer ${process.env.CLAUDECH_API_KEY}` },
});
const { available_tokens, approx_value_usd } = await res.json();
if (BigInt(available_tokens) < 1_000_000n) console.warn(`Low balance: $${approx_value_usd}`);
```

**Python**

```python
import os, requests
r = requests.get("https://api.claudech.com/v1/billing/balance", headers={"authorization": f"Bearer {os.environ['CLAUDECH_API_KEY']}"})
bal = r.json()
if int(bal["available_tokens"]) < 1_000_000:
    print("Low balance:", bal["approx_value_usd"])
```

---

Source: https://claudech.com/docs/api/account
