https://api.rocketverifier.com/v1/creditsCheck your credit balance
In short
GET /v1/credits returns the credits available to your key right now, plus the credits charged for verifications today and this month in UTC. It needs the credits:read scope, works at a zero balance and costs nothing. Organization keys on a pooled organization see the pooled balance.
OAuth scope credits:read
curl https://api.rocketverifier.com/v1/credits \
-H "Authorization: Bearer $ROCKETVERIFIER_API_KEY"import RocketVerifier from "@rocketverifier/sdk";
const rv = new RocketVerifier(process.env.ROCKETVERIFIER_API_KEY);
const { credits, usedToday, usedThisMonth } = await rv.getCredits();
if (credits < 1000) {
// top up before the next import
}import os
from rocketverifier import RocketVerifier
rv = RocketVerifier(os.environ["ROCKETVERIFIER_API_KEY"])
balance = rv.get_credits()
if balance.credits < 1000:
pass # top up before the next import
print(balance.used_today, balance.used_this_month){
"credits": 10000,
"used_today": 150,
"used_this_month": 2500
}Check the balance before a large import, or show it in your own app. The call is free, needs only the credits:read scope and answers even at a zero balance.
Response#
- creditsinteger
Credits available to this credential now.
- used_todayinteger
Credits charged for verifications since 00:00 UTC, before refunds.
- used_this_monthinteger
Credits charged for verifications since the 1st of the month (UTC), before refunds.
What the numbers mean#
credits is what the next charge can draw on. used_today and used_this_month are what verifications cost in the current UTC day and month.
credits: the balance available to this credential now, the same number the auth check uses before every charge.- Usage counts charges, before refunds. A bulk job is charged in full when it starts, and its unknown results are refunded when it completes. The refund raises
creditsbut leavesused_todayandused_this_monthas they were. - Usage covers verifications: single verifications, bulk jobs and email finder checks. List health monitor runs are not included.
- Usage resets at 00:00 UTC each day and on the 1st of each month.
Credits never expire. Buy more in the dashboard.
Organization credit pooling#
When an organization turns on credit pooling, its members' charges draw on the shared pool whenever the pool covers the full charge, and on the member's own balance otherwise.
| Credential | credits returns |
|---|---|
| Personal API key | Your own balance. |
| Organization API key, pooling on | The larger of the pool and the organization owner's own balance. |
| Organization API key, pooling off | The owner's own balance. |
| OAuth token that bills a pooled organization | The larger of the pool and the billed user's own balance. |
Organization keys act as the organization's owner, so usage is reported for the owner's account. Teams explains pooling, roles and organization keys.
Get alerted before you run out#
Subscribe a webhook to credits.low, which fires after a charge leaves 100 credits or fewer, and credits.depleted, which fires when the balance reaches zero. At zero, every endpoint that charges refuses the call with 403 insufficient_credits before doing any work.
What costs credits#
| Action | Cost |
|---|---|
| Single verification | 1 credit per result. Unknown results and suppressed addresses are free. |
| Bulk job or file upload | 1 credit per unique address. Unknown results and suppressed addresses are refunded at completion. |
| Email finder | 1 credit per candidate check with a definite answer, at most 4 per search. |
| List health monitor run | 1 credit per unique address, unknown results refunded. |
| Sandbox keys, list health previews, domain monitors, lookup tools, this endpoint | Free. |
Hard bounces on addresses a job marked deliverable come back as credits through the bounce guarantee.
Errors#
| Status | error.code | When it happens |
|---|---|---|
| 401 | unauthorized, api_key_expired | The key is missing, invalid, revoked or expired. |
| 403 | insufficient_scope | The credential lacks credits:read. |
| 403 | ip_not_allowed | The key has an IP allowlist that does not include the caller. |
| 429 | rate_limited | Too many requests. Wait for the Retry-After seconds. |
Every error uses the standard error shape.
Frequently asked questions
Does checking the balance cost a credit?
No. GET /v1/credits is free and works even when the balance is zero.
Why is used_this_month higher than what I paid for?
The usage numbers count credits when they are charged, before refunds. Bulk jobs are charged up front and refund unknown results at completion, so the refund shows in credits but not in the usage numbers.
Do credits expire?
No. Credits stay in your account until you use them.
How do I get told when credits run low?
Subscribe a webhook to credits.low (fires at 100 credits or fewer) and credits.depleted (fires at zero).
Updated 11 November 2026Suggest an edit