Copy page

Overview

Rate Limits

If you exceed the rate limit, the API returns 429 Too Many Requests.

Rate limits are enforced per endpoint and per plan. Three dimensions are tracked: per-second (rps), per-minute (rpm), and per-day (daily).

Your daily limit is calculated as monthly credits ÷ 5, so you can consume your full monthly quota over approximately 5 working days of heavy use.

Rate Limit Headers

Each API response includes rate limit headers to help you track usage:

RFC-Compliant Headers

• RateLimit-Policy: Describes the rate limit policies (quota and window) for each dimension.
• RateLimit: Current remaining quota and time until reset for each dimension.

Example response headers:

Code
RateLimit-Policy: "rps";q=8;w=1, "daily";q=4000;w=86400
RateLimit:        "rps";r=7;t=1, "daily";r=3842;t=64802

• q = quota (total requests allowed)
• w = window (time window in seconds)
• r = remaining requests
• t = time remaining in window (seconds)

Custom Tracking Headers

Header	Description	Example
x-second-rate-limit	Total per-second request limit	8
x-minute-rate-limit	Total per-minute request limit	150
x-daily-rate-limit	Total daily request limit	4000
x-minute-request-left	Remaining requests for the minute	142
x-daily-request-left	Remaining requests for the day	3842
x-minute-reset-seconds	Seconds until minute limit resets	45
x-daily-reset-seconds	Seconds until daily limit resets	64802

Rate Limits by Plan

Rate limits scale with your subscription plan. Higher plans unlock faster API speeds and higher daily throughput.

Search Endpoints

Daily limit = available_searches / 5

Plan	Credits/mo	Per Second	Per Minute	Per Day
Free	25	1	2	5
Basic	2,500	3	50	500
Growth	5,000	5	80	1,000
Pro	20,000	8	150	4,000
Pro Plus	50,000	10	200	10,000
Scale 100k	100,000	15	300	20,000
Scale 200k	200,000	15	300	40,000
Scale 300k	300,000	15	300	60,000

Applies to: Domain Search, Email Finder, Author Finder, Enrichment, LinkedIn Finder, Similar, Technology, Phone Finder, Phone Validator, Reveal

Verification Endpoint

Daily limit = available_verifications / 5

Plan	Verifications/mo	Per Second	Per Minute	Per Day
Free	50	1	2	10
Basic	2,500	2	40	500
Growth	5,000	3	60	1,000
Pro	20,000	5	100	4,000
Pro Plus	50,000	8	150	10,000
Scale 100k	100,000	10	200	20,000

Applies to: Email Verifier

Email Count & Format Endpoints

Daily limit = available_email_count / 5

Plan	Email Count/mo	Per Second	Per Minute	Per Day
Free	100	1	5	20
Basic	5,000	3	50	1,000
Growth	10,000	5	80	2,000
Pro	25,000	8	150	5,000
Pro Plus	25,000	10	200	5,000
Scale 100k	25,000	15	300	5,000

Applies to: Email Count, Email Format

Email Sources Endpoint

Daily limit = available_sources / 5

Plan	Sources/mo	Per Second	Per Minute	Per Day
Free	100	1	5	20
Basic	500	2	20	100
Growth	500	3	10	100
Pro	500	5	10	100
Pro Plus	200,000	5	200	40,000
Scale 100k	400,000	10	150	80,000

Applies to: Email Sources

How Daily Limits Work

Your daily rate limit is designed so you can fully use your monthly credits within a working week:

Code
daily_limit = monthly_credits / 5

Example: A Pro plan with 20,000 monthly search credits gets a daily limit of 4,000 requests. At max throughput, you'd use all credits in 5 days.

This means:

• Light users won't notice the limit — they'll never come close.
• Heavy users who hit the daily cap can upgrade their plan to get higher throughput.
• All limits reset at midnight UTC each day.

Handle 429 Responses

When you receive a 429, check the Retry-After header for how long to wait before retrying. The x-minute-reset-seconds and x-daily-reset-seconds headers tell you exactly when each limit resets.

Code
curl -i -X GET "https://api.tomba.io/v1/domain-search?domain=example.com" \
    -H "X-Tomba-Key: your_api_key" \
    -H "X-Tomba-Secret: your_secret_key"

429 response example:

Code
{
  "errors": {
    "type": "rate_limit",
    "message": "Rate limit exceeded (daily). Limit is 4000 requests. Retry after 32400 seconds.",
    "code": 429
  }
}

Headers on 429 response:

Code
HTTP/1.1 429 Too Many Requests
Retry-After: 32400
RateLimit-Policy: "rps";q=8;w=1, "daily";q=4000;w=86400
RateLimit: "rps";r=0;t=1, "daily";r=0;t=32400
x-daily-rate-limit: 4000
x-daily-request-left: 0
x-daily-reset-seconds: 32400

Retry with Exponential Backoff

Code
const request = async (retries = 3) => {
    const res = await fetch(
        "https://api.tomba.io/v1/domain-search?domain=example.com",
        {
            headers: {
                "X-Tomba-Key": "your_api_key",
                "X-Tomba-Secret": "your_secret_key",
            },
        },
    );

    if (res.status === 429 && retries > 0) {
        const wait = Number(
            res.headers.get("Retry-After") ||
            res.headers.get("x-minute-reset-seconds") ||
            1
        );
        await new Promise((r) => setTimeout(r, wait * 1000));
        return request(retries - 1);
    }

    return res.json();
};

Retry in Python

Code
import requests
import time

def api_request(url, headers, retries=3):
    for attempt in range(retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 1))
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
            continue

        return response.json()

    raise Exception("Max retries exceeded")

result = api_request(
    "https://api.tomba.io/v1/domain-search?domain=example.com",
    {
        "X-Tomba-Key": "your_api_key",
        "X-Tomba-Secret": "your_secret_key",
    },
)

Check Your Current Usage

You can check your current rate limit usage at any time via the API:

Code
curl -X GET "https://api.tomba.io/v1/rate-limits" \
    -H "X-Tomba-Key: your_api_key" \
    -H "X-Tomba-Secret: your_secret_key"

Response:

Code
{
  "data": {
    "domain-search": {
      "limits": { "rps": 8, "rpm": 150, "daily": 4000 },
      "usage": { "rpm_used": 12, "daily_used": 847 }
    },
    "email-verifier": {
      "limits": { "rps": 5, "rpm": 100, "daily": 4000 },
      "usage": { "rpm_used": 0, "daily_used": 230 }
    }
  }
}

Or view the Rate Limits dashboard in your account.

Overview of Request Costs

Tool	Request Cost	Quota Source
Domain Search	Counted 1 for up to 10 Emails	Searches
Email Finder	Counted as 1 for 1 Email	Searches
Author Finder	Counted as 1 for 1 Email or article person name	Searches
Email & Domain Enrichment	Counted as 1 for 1 Email	Searches
LinkedIn Email Finder	Counted as 1 for 1 Email	Searches
Email Verification	Counted as 1 for 1 Email	Verifications
Phone Finder	Counted as 5 for up to 10 Phones	Searches
Phone Validate	Counted as 1 for 1 Phone	Searches
Reveal search	Counted as 1 for 50 companies	Searches
Email Count	Counted as 1 per domain lookup	Email Count
Email Sources	Counted as 1 per email lookup	Sources

Overview of Bulk Limits and Concurrency

The following table outlines the daily bulk limits and maximum concurrent operations allowed per tool. Staying within these limits ensures optimal performance and resource utilization.

Tool	Limit	Max Concurrent Jobs
Bulks Domain Search	15/day	2
Bulk Email Finder	15/day	2
Bulk Author Finder	15/day	2
Bulk Email Enrichment	15/day	2
Bulk Linkedin Finder	15/day	2
Bulk Email Verifier	15/day	2
Bulks Phone Finder	15/day	2
Bulks Phone Validate	15/day	2
Bulks Company Enrichment	15/day	2
Bulks Similar	15/day	2
Domain export	15/day	2
Reveal search export	15/day	2

Bulk Input Limits

The following input limits apply to bulk upload files or single bulk operations. These limits define the maximum number of rows (inputs) you can include in a single bulk file or request.

Tool / Bulk Job Type	Input Limit (rows)
Bulks Domain Search	25,000
Bulks Company Enrichment	25,000
Bulk Email Finder	10,000
Bulk Email Verifier	20,000
Bulk Email Enrichment	20,000
Bulk LinkedIn Finder	20,000
Bulk Author Finder	5,000
Bulks Similar (domain similar)	5,000
Bulks Phone Finder / Bulks Phone Validate	10,000

If your file exceeds these limits, split it into multiple files or batches to ensure successful processing.

Additional Notes

• When a Domain Search or an Email Finder request doesn't return a result, the request isn't counted. Similarly, for the Email Verifier: if you verify a webmail and no result is provided, the request will not be used.
• Unique requests are counted only once every 30 days against your quota. If you need to re-run a series of requests due to improper data storage or for any other reason, these will not count against your monthly quota. Consequently, you can make identical API requests repeatedly within the same billing period. This flexibility is especially beneficial for developers who are testing integrations.
• All limits are shared across your team members. Please respect these limits. If you need higher limits for an integration app, contact us to discuss options.