Rate limits

To keep the service fast for everyone, each endpoint accepts a maximum number of calls. Go over it and you get an HTTP 429 error.

Endpoint	What it does	Limit
/email-search	Find one email	10 calls / second
/email-verification	Verify one email	10 calls / second
/domain-search	Scan one domain	10 calls / second
/bulk-search	Start a bulk search	1 call / second, up to 5,000 rows each
/bulk-single-searchs/read	Read results	30 calls / minute
/search-files/read	Bulk search progress	15 calls / minute
/scrape/profile, /scrape/company	Scrape one profile or company	20 calls / second
/scrape	Scrape in bulk	20 calls / second, up to 50 rows each
/url-search/profile, /url-search/company	Find one profile or company URL	20 calls / second
/url-search	Find URLs in bulk	20 calls / second, up to 50 rows each
/find-people, /find-companies	Search the lead database	30 calls / second
/find-people/count, /find-companies/count	Count leads	10 calls / second
/reverse-email-lookup	One reverse lookup	20 calls / second
/reverse-email-lookups	Reverse lookups in bulk	15 calls / second, up to 50 rows each

Limits may change.

Staying under the limits

• Reading results is the tightest limit (30 per minute). Wait at least 3 seconds between two reads, or better, use webhooks: they don't count against any limit.
• Use bulk endpoints for lists. One bulk call replaces up to 5,000 single calls.
• On a 429, slow down and retry. Wait 2 seconds, then 4, then 8…

Retry with backoff

async function callIcypeas(url, body, attempt = 0) {
  const res = await fetch(url, {
    method: "POST",
    headers: { "Content-Type": "application/json", Authorization: process.env.ICYPEAS_API_KEY },
    body: JSON.stringify(body),
  });
  if (res.status === 429 && attempt < 5) {
    await new Promise((r) => setTimeout(r, 2000 * 2 ** attempt));
    return callIcypeas(url, body, attempt + 1);
  }
  return res.json();
}