How do I check my AI API balance from code and get a low-balance alert?
In short: On the Wiozen API you read your balance with GET https://api.wiozen.com/v1/balance, using the same key as your normal requests. The response has two fields: balance, an integer in nano-dollars (1 dollar = 1,000,000,000), and formatted, text for display. The request isn't charged and doesn't count toward the daily query limit, so a scheduled job can check it and alert you when it drops below a threshold.
How do I check the balance?
The endpoint takes a single GET with no body. Send your key in the Authorization: Bearer header; an x-api-key header works too. Put your key in the API_KEY environment variable and run:
curl https://api.wiozen.com/v1/balance \ -H "Authorization: Bearer $API_KEY"
The response looks like this:
{"balance": 4370000000, "formatted": "$4.37"}With no key you get 401 Missing API key; with a wrong or revoked key, 401 Invalid API key. That also makes this request the easiest way to test whether a key still works, without calling a model or spending anything.
What do the balance and formatted fields mean?
Wiozen keeps the balance as a whole number of nano-dollars instead of fractional dollars, because a single short request can cost far less than a cent. To get dollars, divide balance by 1,000,000,000: the 4370000000 above is $4.37.
Always use balance for calculations and comparisons. formatted is for showing to people; its number of decimals depends on the amount (amounts under $1 are written with four or six decimals) and its separators can differ by language. Don't try to parse it back into a number.
The balance can go negative. If a single request costs more than what's left, the difference is taken from your next top-up, and until then balance is a negative number. Have your code treat that as "out of balance" as well.
Whose balance is it: the key's or the account's?
The balance belongs to the account, not the key. Whichever key on the same account you query with, you get the same number. Spending from every key comes off this one balance.
A spend limit you set on a key doesn't show in this response. A key that has hit its limit rejects requests with 429 API key spend limit reached even when the account still has balance. You can see per-key spend and limits on the Keys page.
Setting up your own low-balance alert
The balance is checked when a request starts. If what's left doesn't cover the request's estimated cost, the request gets 429 Quota exhausted and doesn't start. For a batch job running overnight or an app your customers use, finding out from that error is too late. A small script that checks the balance regularly and alerts you below a threshold prevents it:
import os
import requests
THRESHOLD_USD = 2.0 # warn below this amount
r = requests.get(
"https://api.wiozen.com/v1/balance",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
timeout=10,
)
r.raise_for_status()
usd = r.json()["balance"] / 1_000_000_000
if usd < THRESHOLD_USD:
print(f"Balance is low: ${usd:.2f}")
# Put your own alert here: email, Slack, Telegram...Running the script hourly from cron or another scheduler is enough for most uses. Pick the threshold from about one day of spending; you can see your average daily spend in the chart on the Usage page.
The balance check doesn't count toward the per-minute request limit either, since that limit only applies to the chat endpoints. Still, there's no need to check the balance before every model request. When the balance falls short you get a 429 anyway; how to tell that error apart from the other causes is in the 429 guide.
Is there an alert in the dashboard or by email?
Yes. The API dashboard home page shows a "Your balance is low" notice once the balance drops below a set amount, and a notice saying requests return 429 once it reaches zero. The low-balance email comes from your Wiozen account and is managed in the account settings on account.wiozen.com.
The threshold for those two alerts isn't an amount you choose. If you want your own threshold, or want the alert to go somewhere other than email (a chat channel, your phone), the script above is the better fit.
The Content Bot reads the balance from the same endpoint and shows it in the plugin panel. The amount it shows is cached for five minutes, so if you still see the old amount right after a top-up, wait a few minutes.
Frequently asked questions
Is the balance check charged?
No. A /v1/balance request doesn't come off your balance and doesn't count toward the daily query limit.
Why is the balance value so large?
The unit is nano-dollars. Divide by 1,000,000,000 to get the dollar amount.
Do different keys show different balances?
No. The balance belongs to the account; every key on the same account returns the same amount.
Can I see my key's spend limit from this endpoint?
No, the response only contains the account balance. Per-key spend and limits are on the Keys page.
Why does my balance show as negative?
If your last request cost more than what was left, the difference is taken from your next top-up. Until you top up, the balance stays negative and requests get 429.
Try a /v1/balance request with one of your keys now. To top up, go to the wallet page.
More guides: How can you use an AI API from Turkey without a credit card? · How do you connect an OpenAI-compatible API to a tool you already use? · How do you calculate the cost of an AI API? · What should I do if my AI API key has leaked? · How do you generate images with an AI API, and what does one image cost? · How much does a speech-to-text API cost, and how is it billed per minute? · Why does my AI API return a 429 error, and how do I fix it? · Why do long AI API requests time out: streaming or non-streaming? · Anthropic Messages API or OpenAI Chat Completions: which one should I use? · What is a context window, and what is a 1 million token context good for? · Which AI model should I choose: deciding by price, context and quality · Why does a reasoning model return an empty answer, and why are thinking tokens charged? · Why is my API balance running out faster than expected? Tracking spend request by request · How do you convert a web page to Markdown to feed it to an AI model? · How do you get AI to write and publish articles in WordPress automatically? · How do you find blog topics from RSS feeds and Google Trends? · Does AI-written content show up on Google and in AI answers? · How do you get internal links into AI-written WordPress articles? · How do you get AI to generate a different featured image for every WordPress post? · How do you write a content brief when an AI writes your blog posts? · What should you watch for when an AI writes recipes for your food blog? · How do you fix errors when connecting a WordPress plugin to your AI API account? · Why does my AI article bot stop halfway in WordPress? "Run is stuck" and LiteSpeed · Why are my scheduled WordPress posts late? WP-Cron and a real server cron · How do I get an AI article bot to write blog posts in English or another language? · What does "Content Bot cannot generate articles" mean? Reading the bot's log · If I delete the WordPress AI article plugin, are the articles it wrote deleted? · How do you do function calling (tool use) with an AI API?