Count People

Count the people that match a set of filters, free of charge.

POSThttps://api.foxreach.io/api/v1/lead-finder/count

Requires an API key with the read scope.

Counting does not use the daily search budget and does not spend reveal credits. It needs a paid plan. filters is an object of filter keys. Call Get Filter Options for the full list of keys and the allowed values for industries and company types. A value outside the provider's vocabulary matches nothing and returns zero rows rather than an error.

Body Parameters#

filtersobjectbodyrequired

Person filters, for example {"jobTitles": ["CTO"], "countries": ["US"]}. At least one filter besides countries is required. companyIds accepts at most 200 entries.

Response#

dataobject

Result.

Show data

totalinteger

Number of matching people.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `read`
`400`	`country_not_available` when a requested country is outside the covered list (`{"detail": {"code": "country_not_available", "message": "...", "allowed": [], "blocked": []}}`); `unknown_filter_keys` naming each key that does not exist (`{"detail": {"code": "unknown_filter_keys", "message": "...", "unknownKeys": [], "validKeys": []}}`); or a message asking for at least one filter besides `countries`
`403`	`upgrade_required` on the Free plan: `{"detail": {"code": "upgrade_required", "limit_type": "lead_finder", "message": "..."}}`. A missing scope also returns 403 with a plain `detail` string
`404`	`Lead Finder is not enabled` while Lead Finder is switched off on this environment
`422`	More than 200 `companyIds` in one call (`too_many_company_ids`), or the body has no `filters` object
`502`	`The data provider is unavailable right now`
`503`	`Lead Finder is not configured` when it is enabled but has no data provider key

Rate Limit#

100 requests per minute, per API key. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset (unix epoch seconds).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Request

curl -X POST "https://api.foxreach.io/api/v1/lead-finder/count" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"jobTitles": ["CTO"], "countries": ["US"]}}'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.lead_finder.count({"jobTitles": ["CTO"], "countries": ["US"]})

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const { total } = await client.leadFinder.count({ jobTitles: ["CTO"], countries: ["US"] });

Response

{
  "data": { "total": 18240 }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026