How to estimate API credit usage and pick the right Finowl pack

Credit-based pricing is simple once you know what each request costs, but it is easy to guess wrong when you are planning a launch or a large backfill. A few minutes of arithmetic up front tells you which pack to buy and whether you need auto top-ups at all.

This guide explains how Finowl credits work, gives a formula for estimating usage, and walks through worked examples for common workloads.

#How Finowl credits work

The rules fit in a short list:

• 1 credit per lookup. Every email breach check, password breach check and gender lookup costs 1 credit. Each item in a gender batch also costs 1 credit.
• 3 credits with AI. A gender lookup costs 3 credits when it requests AI, either with options.ai_mode: "always" or forceToGenderize: true.
• 100 free credits every month. They reset on the 1st (UTC), do not roll over and are used before any purchased credits.
• Prepaid packs never expire. Credits you buy stay on your account until you use them.

#When you are and are not charged

Requests rejected before running, such as a 400 invalid_input, are free. Failed lookups that are confirmed as not billed are also free. Uncertain failures, such as timeouts, are charged, because the lookup may have run. An unknown gender result is a normal successful lookup and is charged.

In a batch, each item reports its own charged_credits, so you can see exactly what a request cost. The credits concept page has the full details.

#The packs

Prices exclude tax. Because credits never expire, a larger pack is not a use-it-or-lose-it commitment. If you are confident you will use the credits over the next year or two, the per-credit savings are significant. See pricing for current details.

#A formula for monthly usage

For each workload, estimate monthly credits as volume per month multiplied by lookups per item, multiplied by credits per lookup. Then add the workloads together and subtract the 100 free credits.

The terms to think about are:

• Volume per month. New signups, contacts imported, accounts re-checked.
• Lookups per item. Usually 1, but some flows call more than one endpoint, such as a password check and an email check at signup.
• Credits per lookup. 1, or 3 for gender lookups that request AI.

Add a margin of 10 to 20 percent for retries after uncertain failures, growth and one-off jobs.

#Measure a sample before you commit

Estimates are only as good as their inputs. Before buying a large pack, run a small, representative sample through the batch endpoint and add up charged_credits. That tells you the real cost per item, including unknown results and any item errors.

import os
import requests

items = [
    {"id": "s1", "type": "name", "value": "Jane", "country": "US"},
    {"id": "s2", "type": "email", "value": "li.wei@example.com"},
    {"id": "s3", "type": "username", "value": "jsmith_92"},
]

resp = requests.post(
    "https://api.finowl.co/v1/gender/batch",
    json={"items": items},
    headers={
        "Authorization": f"Bearer {os.environ['FINOWL_API_KEY']}",
        "Content-Type": "application/json",
    },
    timeout=60,
)
resp.raise_for_status()
results = resp.json()["data"]

charged = sum(r["charged_credits"] for r in results)
unknown = sum(
    1 for r in results
    if "data" in r and r["data"]["result_status"] == "unknown"
)
print(f"{charged} credits for {len(items)} items, {unknown} unknown")

Scale the result up to your full volume. If a large share comes back unknown, that is a signal to clean inputs or to plan a smaller, targeted AI pass rather than paying for AI on everything.

#Worked examples

#Example 1: a small app checking passwords at signup

A product gets 1,500 signups a month and checks every new password against breach data. Users who pick a breached password retry, which adds about 10 percent more checks.

• 1,500 x 1.1 x 1 credit = 1,650 credits
• Minus 100 free credits = 1,550 credits per month
• About 18,600 credits per year

Pick: Starter (10,000 for $29) lasts about six months. A Pro pack (100,000 for $99) would last for years and costs less per credit, so if the product is growing, Pro is the better buy. The check uses POST /v1/breaches/password, which never logs or stores the password.

#Example 2: monthly breach monitoring

A SaaS product re-checks 30,000 active customer emails every month and checks 2,000 new signups.

• (30,000 + 2,000) x 1 credit = 32,000 credits per month
• Minus 100 free credits = 31,900 credits
• About 383,000 credits per year

Pick: Growth (500,000 for $249) covers more than a year. Buying Pro packs repeatedly would cost about $396 for the same year, so Growth is clearly cheaper. The approach is covered in email breach monitoring for customer accounts.

#Example 3: a one-time CRM backfill with gender enrichment

A marketing team wants aggregate gender insight across 600,000 contacts using first names and country hints. Batch items default to ai_mode: "off", so each costs 1 credit.

• 600,000 x 1 credit = 600,000 credits

Pick: One Business pack (1,000,000 for $399) covers the backfill and leaves 400,000 credits for ongoing work. A Growth pack plus a Pro pack would give exactly 600,000 for $348, which is cheaper if you have no further use planned. Compare the total you expect to use, not just this job.

#Example 4: mixing dataset and AI lookups

An app enriches 20,000 usernames a month. About 70 percent resolve from the dataset. For the rest, the team uses AI to read nicknames and handles, which costs 3 credits each.

One way to do it: run every username with forceToGenderize: true, which costs 3 credits for each lookup, or 60,000 credits.

A cheaper way: run a first pass with the dataset only, then send only the unknown results for an AI pass.

• First pass: 20,000 x 1 = 20,000 credits
• AI pass on 30 percent: 6,000 x 3 = 18,000 credits
• Total: 38,000 credits per month

That is 22,000 credits a month saved, and over a year the difference is enough to change which pack you need. The AI mode guide explains how each mode behaves, so you can decide which lookups genuinely need AI.

#Auto top-ups

If your usage is unpredictable, auto top-ups help keep your account from running dry. They are available once you save a card, and they buy more credits automatically so production traffic is not interrupted. This matters because running out of credits returns 429 quota_exceeded, which can break a signup flow or stall a batch job.

Some tips:

• Size top-ups to cover at least a month of typical usage, so you are not topping up constantly.
• Keep alerting on quota_exceeded anyway, in case a card fails.
• Pause bulk jobs, rather than retrying, if they hit quota_exceeded.

#Avoiding wasted credits

Most waste comes from paying for lookups that never needed to happen.

#Validate inputs first

Rejected requests are free, but they still cost time and clutter logs. More importantly, garbage that passes validation, such as placeholder names like "test" or role addresses like info@, costs a credit and returns nothing useful. Filter it out before calling the API.

#Deduplicate

The same email or name appearing twice in a list costs twice. Normalize and deduplicate before enriching, and cache results for values you have already looked up, such as common first names in a gender backfill.

#Retry carefully

A 429 rate_limited response is safe to retry after the Retry-After delay. For 5xx and 504 responses, the lookup may have run and may have been charged, so blind retries can double your cost. Our post on safe retries for paid APIs explains how to retry without paying twice.

#Do not resend whole batches

In a gender batch, a 200 can include item-level errors. Retry only the failed items, never the whole batch, or you will pay again for every item that already succeeded.

#Use the free tier for testing

The 100 free monthly credits are enough to build and test an integration. Try requests in the Sandbox before wiring up code, and keep a separate test key so experiments do not eat into production budgets.

#A quick checklist

1. List every workload and its monthly volume.
2. Multiply by lookups per item and credits per lookup.
3. Add a 10 to 20 percent margin, subtract 100 free credits.
4. Multiply by 12 and compare packs by total annual cost.
5. Turn on auto top-ups if your volume is unpredictable.

#Frequently asked questions

#How many credits does a Finowl lookup cost?

Each lookup or batch item costs 1 credit. A gender lookup costs 3 credits when it requests AI with ai_mode: "always" or forceToGenderize: true.

#Do free credits roll over?

No. You get 100 free credits every month, they reset on the 1st (UTC) and are used before purchased credits. Purchased pack credits never expire.

#Am I charged for failed requests?

Requests rejected before running, such as invalid input, are free, and failures confirmed as not billed are free. Uncertain failures such as timeouts are charged because the lookup may have run.

#Which pack should I start with?

If you are testing, start with the 100 free monthly credits. For low steady volume, Starter or Pro works well; for monitoring or backfills in the hundreds of thousands, Growth or Business offers the lowest price per credit.