> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kymaapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit balance

> Your spendable balance, lifetime totals and rate-limit tier.

Read-only. Authenticate with an API key (`kyma-...`) or a session token (`ks-...`) as `Authorization: Bearer ...`.

## Response

```json theme={null}
{
  "balance": 4.2181,
  "lifetime_purchased": 5,
  "lifetime_earned": 0.5,
  "lifetime_spent": 1.2819,
  "read_ok": true,
  "tier": 1,
  "tier_name": "Tier 1",
  "tier_rpm": 600,
  "low_balance": false,
  "nudge": null
}
```

| Field | Meaning |
| - | - |
| `balance` | Spendable credit, in US dollars |
| `lifetime_purchased` | Everything you have paid in. Your tier is set by this number |
| `lifetime_earned` | Credit you received without paying: bonuses, referrals, gifts and refunds |
| `lifetime_spent` | Everything your requests have been charged |
| `read_ok` | `false` when the balance could not be read. The numbers are then zeros, not your balance: ask again |
| `tier`, `tier_name`, `tier_rpm` | Your rate-limit tier and its requests per minute. All tiers: [`GET /v1/limits/tiers`](/api-reference/limits-tiers) |
| `low_balance` | `true` when `balance` is under \$0.05 |
| `nudge` | When `low_balance` is `true`, `{message, action}` with a link to add credits; otherwise `null` |

The balance is cached for up to 30 seconds, so a charge can take that long to show here.

## Errors

| Code | `error.type` | Means |
| - | - | - |
| `401` | `auth_required` | No `Authorization: Bearer` header |
| `401` | `invalid_credentials` | Unknown or revoked key, or expired session |

<RequestExample>
  ```bash cURL theme={null}
  curl https://kymaapi.com/v1/credits/balance \
    -H "Authorization: Bearer kyma-your-api-key"
  ```
</RequestExample>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.