Keys and access
- The API key lives in a server-side secret store and is read from the environment, never from source code or browser code. See authentication.
- You know how to rotate it: create a new key on the API page, deploy it, then delete the old key.
- A
403is surfaced as a configuration error, not retried. A missing or invalid key returns403with{"detail": "Authentication credentials were not provided."}.
Credits
- You know the cost of every call you make. See credits and pricing. For example, a phone number lookup is 15 credits and a person role search is 1.
- You cache results you’ve already paid for, so a retry, page refresh or duplicate job doesn’t buy the same lookup twice.
- You only call contact lookups for the people you’ll actually use. Search first (1 credit), then look up contacts for the results you keep. See Choose the right endpoint.
- Spend is monitored with the credit usage endpoints, with an alert when a day’s total is unusual.
- Agents and automations that call Forager have a credit limit or a human approval step.
Rate limits and retries
-
429responses back off before retrying. Autocomplete allows 10 requests per second and feedback 60 per minute, per account. See API errors and rate limits. - Work email enrichment for many people uses the bulk work email lookup, not a loop over the single lookup.
- Polling a single work email lookup follows its
Retry-Afterheader; batch polls back off between requests. Polling a lookup or batch never consumes credits.
Data quality
- An empty result is handled as “not found”, with a fallback in your product.
- Call and email outcomes are sent back with the feedback endpoints.
- You handle personal data under your own privacy obligations. See Forager’s privacy policy and security and privacy.
Monitoring
- You log the endpoint, status code and latency for each request, never the API key or full response bodies containing personal data.
- Someone on your team follows status.forager.ai and the changelog, which has an RSS feed.