---
title: "Balance"
method: GET
path: "/api/v1/usage/balance"
tags: ["usage"]
---

# Balance

`GET /api/v1/usage/balance`

## Request

- Base URL: `https://api.capy.ai`
- URL: `https://api.capy.ai/api/v1/usage/balance`
- Auth: HTTP bearer

## Response `200`

UsageBalance

- UsageBalanceEncoded
  - `currency` 'USD', required: The currency of every dollar amount in the response.
  - `remainingDollars` union, required: Spendable plan and purchased credit, valued in dollars; not a cash or refundable balance. Negative once overdrawn. Null when the organization has no credit balance or an unlimited grant.
    - number
    - 'Infinity' | '-Infinity' | 'NaN'
  - `unlimited` boolean, required
  - `periodStart` string, nullable, required: Start of the current subscription period. Null without a plan; usage windows then default to the UTC calendar month.
  - `periodEnd` string, nullable, required: End of the current subscription period; null without a plan.

## Other responses

- `401`: capy/Unauthorized
- `403`: capy/Forbidden
- `429`: capy/RateLimited
- `503`: capy/BillingAuthorityUnavailable

## Changes

- **2026-10-29** `6077fbba29f8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/capy/apis/capy-api/changes/api/v1/usage/balance/get.md)

---

[API](https://skmtc.dev/capy/apis/capy-api.md) - [All operations](https://skmtc.dev/capy/apis/capy-api/llms.txt) - [OpenAPI document](https://skmtc.dev/capy/apis/capy-api/revisions/4663f7dc4e39?raw)