Rate limits

To keep the service fast for everyone, the API limits how many requests your account can send to each endpoint in a minute. Limits apply per account, not per key: two keys on the same account share them.

How the limits work

• Each endpoint has its own limit, counted over the last 60 seconds. Calls to one endpoint don't use up another's.
• For an endpoint with an id in its path, such as a job's status, each job or list has its own count.
• Endpoints that aren't in the table below have no per-minute limit of their own. Call them at a sensible pace all the same.
• The MCP server has one limit for all tools together: 60 requests a minute per account.

Limits per endpoint

Requests per minute, per account.

The API reference describes each endpoint.

When you hit a limit

The API answers 429 with the code RATE_LIMITED, and the message names the limit. Nothing was run and nothing was charged for that request, so it's safe to send it again.

The response includes a Retry-After header with the number of seconds to wait: 60 for the REST API, 5 for the MCP server.

To handle it:

1. Wait the number of seconds in Retry-After.
2. If a response has no Retry-After (for example a 502, 503 or 504), back off instead: wait 2 seconds, then 4, then 8, and so on, up to about a minute.
3. Retry the same request.

import time
import requests

def post_with_retry(url, payload, key, tries=5):
    wait = 2
    for _ in range(tries):
        r = requests.post(
            url,
            json=payload,
            headers={"Authorization": f"Bearer {key}"},
            timeout=90,
        )
        if r.status_code not in (429, 502, 503, 504):
            return r
        retry_after = r.headers.get("Retry-After")
        time.sleep(int(retry_after) if retry_after and retry_after.isdigit() else wait)
        wait = min(wait * 2, 60)
    return r

The same approach works for 502, 503 and 504, which mean a temporary problem on our side.

Stay under the limits

• Use bulk endpoints for lists. One bulk job of 10,000 addresses is one request to start, a few to poll and a few to read. Ten thousand single calls will hit the limit and take longer.
• Poll calmly. Every 5–10 seconds is plenty for a job's status. See Long-running jobs.
• Spread out single calls. If you call the single endpoints from a spreadsheet tool or automation, add a short pause between rows. In Clay, we recommend setting each filtrat column to 60 requests a minute. That's a recommendation for a column's throughput, well under the endpoint limits above, so retries and other tools have room: see Recommended column settings.
• Set a long enough timeout. Resolving a catch-all address can take up to a minute. A client that gives up after a few seconds and retries sends more requests, not fewer. Use a timeout of 90 seconds for verification and finding.

Need more?

If your use case needs a higher sustained rate, email support@filtrat.io with what you're building and roughly how many requests a minute you need.