REST API
Count people
How many people match — and at how many companies — before you pull them.
POST
/v1/people/countParameters
companiesobjectoptionalScope the people to companies. Combine freely with filters/site_text below (all must hold). Without
companies the scope is every indexed company that passes the filters.filtersobjectoptionalCOMPANY facets (as in search_companies: country, vertical, leaf, headcount, tech …; see list_filters) — the company’s, not the person’s
exclude_filtersobjectoptionalsame shape, negated
site_textobjectoptionalwords on the company’s own pages. WORDS ON THE COMPANY’S OWN CRAWLED PAGES — exact vocabulary the profile may not restate (a certification, a
exclude_listsstring[]optionalids of your exclusion lists (get_lists) to apply to this call (up to 20 items)
exclude_domainsstring[]optionalextra domains/URLs/e-mails to keep out of this call’s results (up to 1000 items)
exclude_peopleobjectoptionalkeep your existing contacts out of the results (exact match)
clientstringoptionalAGENCIES: which of your clients this call is for (e.g. ‘acme’). That client’s always-exclude lists apply on top of your organization-wide ones — never another client’s. Set once per client conversation.
personobjectoptionalWHO: every field narrows (AND); a list is any-of. Values: list_people_values.
waterfallobject[]optional(up to 10 items)
group_bystring[]optional(up to 3 items)
group_sizeintegeroptional(min 1, max 100)
What your agent reads
The tool description exactly as an MCP client receives it in tools/list — it doubles as the full behaviour of the endpoint.
How many people match — and at how many companies — before you pull them. Same arguments as search_people
(`person` or `waterfall`, `companies`, `filters`, `site_text`, exclusions); nothing is returned but numbers, and
nothing is charged per person. With `waterfall`: companies per tier and how many matched none.
`group_by` (≤3 of: seniority, function, sub_function, role, territory, employment, tier, email_status, country,
vertical, headcount) splits the people count.
Errors follow one format.