Skip to content
RocketVerifierDOCS
GEThttps://api.rocketverifier.com/v1/credits

Check 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"
Response 200
{
  "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.

  • 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 credits but leaves used_today and used_this_month as 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.

Credentialcredits returns
Personal API keyYour own balance.
Organization API key, pooling onThe larger of the pool and the organization owner's own balance.
Organization API key, pooling offThe owner's own balance.
OAuth token that bills a pooled organizationThe 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#

ActionCost
Single verification1 credit per result. Unknown results and suppressed addresses are free.
Bulk job or file upload1 credit per unique address. Unknown results and suppressed addresses are refunded at completion.
Email finder1 credit per candidate check with a definite answer, at most 4 per search.
List health monitor run1 credit per unique address, unknown results refunded.
Sandbox keys, list health previews, domain monitors, lookup tools, this endpointFree.

Hard bounces on addresses a job marked deliverable come back as credits through the bounce guarantee.

Errors#

Statuserror.codeWhen it happens
401unauthorized, api_key_expiredThe key is missing, invalid, revoked or expired.
403insufficient_scopeThe credential lacks credits:read.
403ip_not_allowedThe key has an IP allowlist that does not include the caller.
429rate_limitedToo 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