Skip to main content
You have a list of company domains and want the decision-makers at each one. The obvious loop is one search_people call per company per seniority level. That loop makes several times the calls it needs, and on a long list it turns into tens of thousands of requests in a few minutes. Three changes cut it down.

​
1. Pass every seniority level in one call

seniority takes a list. A list matches any of its values, so one call returns everyone at those levels, ranked together. Don’t do this. It’s six calls for one company:
Do this. It’s one call for the same company:
You get the same people back from one request instead of six.
seniority only accepts these values: Intern, Entry, Senior, Manager, Director, VP, Head, C Suite, Owner, Partner. "C Suite" has a space, not a hyphen. Any other value, such as "Founder", is rejected. To find founders, use title instead.

​
2. Batch domains when you don’t need a per-company quota

company_domain also takes a list. If you want decision-makers across your list rather than a fixed number per company, send up to 100 domains in one call and raise limit to the maximum of 25:
Read company.domain on each result to see which company a person belongs to. Page through with offset until you’ve collected total results.
Results across all domains are ranked together, not split per company. A larger company can fill a page on its own. If you need “up to 5 people at every company,” keep one call per domain and use step 1.

​
3. Treat not_found as the answer

A search that matches nothing returns HTTP 200 with status: "not_found" and total: 0. It costs no tokens. It still counts as one request against your Fair Use requests limit. not_found means nobody at that company is in the index. It isn’t a transient error, so don’t retry it. Running the same search again returns the same empty result and uses another request. Expect a low hit rate on lists of very small businesses, such as local shops, contractors, and single-location services. Many of them have no employees in the index at all. A 5% hit rate on a list like that reflects the data, not a bug.

​
Pace large runs

Even with fewer calls, don’t send a whole list at once. Spread the run out so you stay inside your plan’s 5-hour window and clear of the burst guard, which returns 429 with rate_limited. If you run searches in parallel, stay at or below your plan’s concurrent search limit — going over returns 429 with search_concurrency_exceeded, which you can retry after 1 second. See Rate limits for how to space scheduled runs.

​
Summary

Searching for people

Filters, fill rates, and paginating without wasting records.

Rate limits

How requests and records count against your plan.