Get the account's current API credit balance
GET /api/usage/credits/
Free
What it returns
Your account's current API credit balance plus the plan and billing context that puts the number in context — credits_used, credits_remaining, total_credits, usage_percentage, current plan_name and subscription_status, and the renewal_date when the allowance resets. Sourced from your subscription record and live credit-usage counters; no third-party data providers involved.
When to use it
- Display the user's remaining credits in your dashboard.
- Poll before a batch job to check headroom — calls are free (0 credits).
- Surface subscription_status to gate paid features in your UI.
- Compare renewal_date to "now" to show countdown timers.
Pricing
Free. This endpoint costs 0 credits per call. Safe to poll on every page load.
Errors
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key. |
| 403 | API key valid but account is suspended. |
FAQ
Why is credits_remaining null?
Your plan is unlimited or a custom plan with no fixed per-period cap. The other balance fields are also null in that case. credits_used is always populated.
When does the balance reset?
At renewal_date. For monthly plans, that's the Stripe billing-period end. For yearly plans, the credit allowance resets monthly even though the subscription itself renews yearly — renewal_date is the next monthly reset, not the yearly one.
What if the user has no subscription at all?
plan_name, total_credits, and most other fields are null. credits_used is still populated (any credits consumed outside a subscription period are reported). subscription_status is an empty string.
Responses
200