---
title: "Check Your API Credit Balance — Account API"
description: "Return the current API credit balance for your Homesage.ai account, including credits consumed this billing cycle and credits remaining. Costs 0 credits."
---

# 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.