Credits and usage
Most Tomba endpoints consume credits from a monthly allowance. This page is the reference for what each request costs, when it's free, and how to check what you have left. Throttling is separate; see Rate limits.
Quotas
Your account has four credit balances:
| Balance | Used by |
|---|---|
| Search credits | Finders, enrichment, phone lookups, company search, similar domains |
| Verification credits | Email verifier |
| Email count credits | Email count, email format, location |
| Sources credits | Email sources |
New accounts start on the Free plan, with 25 search credits per usage window. Paid plans include equal search and verification allowances:
| Plan | Search credits | Verification credits | Availability |
|---|---|---|---|
| Basic | 2,500 | 2,500 | Self-serve |
| Growth | 5,000 | 5,000 | Self-serve |
| Pro | 20,000 | 20,000 | Self-serve |
| Pro Plus | 50,000 | 50,000 | Self-serve |
| Scale 100k | 100,000 | 100,000 | On request |
| Scale 200k | 200,000 | 200,000 | On request |
| Scale 350k | 350,000 | 350,000 | On request |
| Enterprise | By contract | By contract | Contact sales |
Prices are on the pricing page; Tomba Enterprise covers the Enterprise plan. Email count and sources allowances depend on the plan and appear in GET /v1/me.
Usage window. Monthly subscriptions reset at each billing date. Free, yearly, and Enterprise plans reset every 30 days; yearly plans receive a monthly allowance, not an annual pool. Unused plan credits don't carry over.
Credit packs. Pay-as-you-go packs add credits on top of your plan. Pack credits last 365 days from purchase, carry over between windows, and are used only after your plan credits run out, oldest pack first.
Workspaces. Members of a workspace use the owner's credits. The owner can set a search or verification limit for each member; a member who reaches it gets 402 quota_exceeded.
Auto-upgrade. If you turn on auto-upgrade in the dashboard, your subscription moves to the next plan in the table above when 10% of your search credits remain. It never moves to Enterprise.
Credit costs
A request is charged only when it succeeds (HTTP 200) and returns a result that meets the "Charged when" condition. Errors, 429 responses, and 451 responses cost nothing.
| Endpoint | Cost | Charged when |
|---|---|---|
GET /domain-search | 1 search credit per 10 results requested with limit, rounded up (the default limit of 10 costs 1), plus 5 per returned address with phone data | At least one email address is returned |
GET /email-finder | 1 search credit, or 6 with phone data | An address is returned with a verification status other than unknown |
GET /author-finder | 1 search credit | An address is returned |
GET /enrich | 1 search credit, or 6 with phone data | An address is returned with a verification status other than unknown |
GET /linkedin | 1 search credit, or 6 with phone data. With full=true: 1 per returned address plus 5 per phone number | An address is returned |
GET /email-verifier | 1 verification credit, plus 5 per phone number returned with enrich_mobile=true | The status is not disposable or unknown |
GET /phone-finder | 5 search credits, or 1 when the request includes domain | A valid phone number is returned |
GET /phone-validator | 1 search credit | Every successful response, including one with no data |
POST /reveal/search | 1 search credit per request | At least one company is returned |
GET /similar | 1 search credit per 10 results requested with limit, rounded up | Results are returned |
GET /people/find | 1 search credit | A person is returned |
GET /companies/find | 1 search credit | A company is returned |
GET /combined/find | 2 search credits | A person is returned |
GET /email-count | 1 email count credit | Every call |
GET /email-format | 1 email count credit | Every successful call, including an empty result |
GET /location | 1 email count credit | Every successful call, including an empty result |
GET /email-sources | 1 sources credit | Sources are found |
GET /technology | Not charged. Requires a positive search balance. | — |
GET /domain-suggestions, GET /domain-status, Logo API | Free | — |
Account and management endpoints (/me, /usage, /logs, /rate-limits, /keys, /leads, /flag) | Free | — |
| Bulk jobs | Per row, depending on the bulk type | When you first download the results |
"Phone data" means phone numbers returned because you set enrich_mobile=true.
If a request would cost more credits than you have left, it fails with 402 quota_exceeded before any work is done. When the email count or sources balance is exhausted, those endpoints return 429 rate_limit instead.
Duplicate requests
Sending the same request again within the same usage window costs nothing. The response still returns the data.
- Same request means the same user, endpoint, and parameters. Changing any parameter, including
page,limit,enrich_mobile, orwebhook_url, makes a new request. - Some endpoints compare only their main input: the URL for author finder and LinkedIn finder, the email for person and combined enrichment, and the domain for company enrichment.
- The rule is per user. Two members of a workspace sending the same request are each charged.
- It doesn't apply to email count, email sources, or bulk jobs.
- It resets with your usage window, so a repeat just after renewal is charged.
Refunds for incorrect data
When an email address returned by Tomba hard-bounces, report it with POST /v1/flag, flag_type email and reason hard_bounce. After Tomba reviews and confirms the report, one search credit is returned to your current usage window.
Other flag types and reasons correct the data but don't refund credits. A second report for an item that already has a pending report returns 409 duplicate_record. You can also review your reports under Flags in the dashboard.
Free plan limits
On the Free plan, outside a workspace:
- Domain search returns at most 10 addresses. A
limitabove 10 fails with400 params_invalid, andpageis always 1. - Company search returns only the first page. A request for a later page returns the first page again, without the keyword, founded, revenue, type, technology, similar, SIC, and NAICS filters.
- Similar domains and technology return only data Tomba already has, without a live lookup.
Check usage
| Where | What it shows |
|---|---|
| Usage in the dashboard | Balances and usage over time, for you or your whole workspace |
GET /v1/me | pricing.available_searches and pricing.available_verifications (plan plus pack credits); requests.domains and requests.verifications with available (the allowance) and used; the current window in issued and expired |
GET /v1/usage | Daily usage per balance |
GET /v1/logs | Charged requests with their cost; repeats appear with cost 0 |
| Response headers | X-Search-Limit / X-Search-Remaining, X-Verify-Limit / X-Verify-Remaining, X-Count-Limit / X-Count-Remaining, X-Sources-Limit / X-Sources-Remaining on charged endpoints. Values are from before the current request. |
In requests.domains and requests.verifications, the remaining balance is available minus used.