Count contacts
Get the size of your audience without paging through it. Reads a maintained counter, so it answers in milliseconds however large your list grows.
Requires the contacts:read scope.
How many contacts you have, without reading any of them.
Query parameters#
| Parameter | Type | Description |
|---|---|---|
project |
string | Required, always. A prj_ handle |
As on list, a key pinned to one project still has to name it.
Omitting project returns 400 parameter_missing.
What comes back#
total is your live audience: it excludes test contacts, deleted contacts, and anything held for
review. Alongside it you get the breakdown by status and by stage, plus flagged, the signups
the spam guard held for review at capture. The status and stage maps break down the same live
population.
Both breakdowns are maps of whatever buckets that project actually has. status can also carry
blocked, and stage carries your pipeline stage keys, so a project with a custom activated
stage gets an activated count here. A bucket that is empty is omitted rather than sent as zero.
Why this exists#
The count comes from a maintained counter, not from a COUNT(*). At a million contacts a scan
is seconds; this is milliseconds, and it does not get slower as you grow.