get_credit_balance

io.github.Vaquill-AI/vaquill-mcp · Verify this server

Returns the credits this API key's account can spend right now. **Free.** This endpoint is never charged, so you can poll it to drive alerting or a pre-flight check without the check itself costing you anything. It is rate limited like every other key-authenticated route. **Authentication:** any valid `vq_key_` key. No particular scope is required. ## What the number means `creditsRemaining` is derived from your live credit buckets under the same expiry rule the billing path applies, so it is what a call would actually be allowed to spend, not a cached figure that a nightly job later corrects. It is the same field name metered responses use, so you can read `creditsRemaining` the same way everywhere. ## Not all credits behave alike Read `bySource` before assuming a balance is durable. `subscription` credits are use-it-or-lose-it and are forfeited at the end of the period, while `payg` credits you purchased burn last and persist. `nextExpiry` tells you what is about to be forfeited and when, which is the one thing a balance alone cannot. ## Two separate ceilings Credits are how MUCH you may spend; `rateLimit` is how FAST you may call. They are independent, so a healthy balance does not exempt you from throttling and staying under the rate limit does not pay for a call. `rateLimit` has your plan applied and lets you size a client before issuing a request. Every response also carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` for the per-minute window, plus `X-RateLimit-Limit-Day` and `X-RateLimit-Remaining-Day` for the daily backstop; those report the same ceilings with your live headroom. ## Example ```bash curl https://api.vaquill.ai/api/v1/credits/balance \ -H "Authorization: Bearer $VAQUILL_API_KEY" ``` ```json { "creditsRemaining": 103039.0, "usdRemaining": 1030.39, "bySource": [ { "source": "payg", "credits": 102539.0 }, { "source": "subscription", "credits": 500.0 } ], "nextExpiry": { "at": "2026-10-01T00:00:00Z", "credits": 500.0 }, "plan": "business", "totalPurchased": 150000.0, "totalConsumed": 46961.0, "asOf": "2026-09-19T12:34:56Z" } ```