# 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.

Source: https://getlaunchlist.com/help/docs/api/contacts-count

---

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](/help/docs/api/contacts-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.

> [!WARNING] Never page a list to count it
> Fetching every page to arrive at a number costs you your whole rate limit and gives a worse answer
> than this endpoint returns instantly.

## Next

- [List contacts](/help/docs/api/contacts-list)
- [Rate limits](/help/docs/api/rate-limits)