--- title: "Get your credit balance" method: GET path: "/api/v1/credits/balance" tags: ["Credits"] --- # Get your credit balance `GET /api/v1/credits/balance` ## Request - Base URL: `https://api.vaquill.ai` - URL: `https://api.vaquill.ai/api/v1/credits/balance` - Auth: one of: - HTTP bearer - API key in header `X-API-Key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Returns the credits this API key's account can spend right now, derived from your live credit buckets under the same expiry rule the billing path applies. Free, never charged, and open to any valid `vq_key_` key (no scope required), so you can poll it for alerting or a pre-flight check. It is rate limited like every other key-authenticated route; see the rate-limit docs for the `X-RateLimit-*` headers. `creditsRemaining` is the same field name metered responses use. Credits are how much you may spend and `rateLimit` is how fast you may call; the two are independent. Read `bySource` and `nextExpiry` before assuming a balance is durable. ## Response `200` Current spendable balance for the calling key's account. - ExternalCreditBalanceResponse: Spendable credit balance for the calling API key's account. - `creditsRemaining` number, required: Credits you can actually spend right now, the same field name metered responses return. Derived from your live credit buckets under the billing path's expiry rule, so it never promises credits a call would refuse to spend. - `usdRemaining` number, required: `creditsRemaining` in USD, at the published conversion rate (1 credit = $0.01). Provided so you do not have to hardcode the rate; `GET /api/v1/api-credits/pricing` is its source of truth. - `bySource` CreditSourceBreakdown[]: `creditsRemaining` split by funding source; always sums to it. `subscription` credits are use-it-or-lose-it at the period end, while `payg` credits you bought persist and burn last. - `source` string, required: Where the credits came from. `bonus` (signup grant), `subscription` (plan allowance, use-it-or-lose-it), `payg` (purchased packs) and `comp` (complimentary) exist today, and this list is not closed: read the values rather than matching on a fixed set. - `credits` number, required: Credits remaining in this source. 1 credit = $0.01. - `nextExpiry` CreditExpiry: The soonest expiry, and what dies with it. - `at` string, date-time, required: UTC instant at which the next credits expire. - `credits` number, required: Credits that expire at that instant. They stop being spendable immediately at `at`, not when the nightly sweep records it. - `plan` string, nullable: Active API subscription tier, or `null` on pay-as-you-go. Also determines your rate-limit multiplier. Briefly cached, so a subscription change made seconds ago may not be reflected yet; `creditsRemaining` is always live. - `totalPurchased` number, required: Lifetime credits added to this account. - `totalConsumed` number, required: Lifetime credits spent by this account. - `rateLimit` CreditRateLimit: Request-rate ceilings in force for the calling key. A second, independent ceiling alongside credits, and the two are unrelated: you can hold credits and still be throttled, or sit far under these limits and be refused for an empty balance. - `perMinute` integer, required: Requests allowed per minute on this key, plan multiplier already applied. - `perHour` integer, required: Requests allowed per hour on this key. - `perDay` integer, required: Requests allowed per day on this key. - `asOf` string, date-time, required: When this balance was computed. The value is live, not cached, so this is the instant the buckets were read. ## Other responses - `401`: Missing, malformed or unrecognised API key. This endpoint accepts only a `vq_key_` API key; a dashboard session token is rejected. - `429`: Request-rate ceiling exceeded. Retry after the `Retry-After` header. Being throttled says nothing about your balance. - `500`: Internal error (`internal_error`, retryable). Any credits charged for the call are refunded; retry with backoff and quote `requestId` to support if it persists. ## Changes - **2026-11-07** `340c0d24d0b6`: 1 info - added the non-success response with the status `500` [Operation history](https://skmtc.dev/vaquill/apis/vaquill-developer-api/changes/api/v1/credits/balance/get.md) --- [API](https://skmtc.dev/vaquill/apis/vaquill-developer-api.md) - [All operations](https://skmtc.dev/vaquill/apis/vaquill-developer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/vaquill/apis/vaquill-developer-api/revisions/340c0d24d0b6?raw)