Count Companies

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

POSThttps://api.foxreach.io/api/v1/lead-finder/companies/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. Company filters have their own keys; see companyFilterKeys in Get Filter Options.

Body Parameters#

filtersobjectbodyrequired

Company filters, for example {"industries": ["Computer Software"], "minHeadcount": 50, "countries": ["US"]}. At least one filter besides countries is required.

Response#

dataobject

Result.

Show data

totalinteger

Number of matching companies.

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
`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/companies/count" \
  -H "X-API-Key: otr_your_key" \
  -H "Content-Type: application/json" \
  -d '{"filters": {"industries": ["Computer Software"], "minHeadcount": 50, "countries": ["US"]}}'

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
result = client.lead_finder.count_companies({"industries": ["Computer Software"], "minHeadcount": 50})

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const { total } = await client.leadFinder.companiesCount({ industries: ["Computer Software"], minHeadcount: 50 });

Response

{
  "data": { "total": 4120 }
}

Was this page helpful?

View as MarkdownLast updated November 2, 2026