---
title: "Contact statistics"
method: GET
path: "/v1/sites/{site_id}/contacts/stats"
tags: ["Contacts"]
---

# Contact statistics

`GET /v1/sites/{site_id}/contacts/stats`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/contacts/stats`
- Auth: HTTP bearer

The number of contacts matching the filters now, by status. Takes the same
filters as `list_contacts`; call it for totals instead of walking the list.
`all` is the sum of the three statuses. Deleted contacts are not counted.
`segment_id` applies the conditions of the segment as they are now.

## Path parameters

- `site_id` integer, required

## Query parameters

- `status` string[]: Any of these statuses; repeat for several. `subscribed`: subscribed, with double opt-in confirmed or not needed; `unsubscribed`: unsubscribed, never subscribed or awaiting double opt-in; `bounced`: the address bounced or failed the e-mail check
- `tag_ids` integer[]: Tagged with any of these tag ids from `list_tags`; repeat for several
- `country` string[]: In any of these countries, ISO 3166-1 alpha-2 codes such as `US`; repeat for several
- `email` string[]: With any of these whole addresses, without case; repeat for several
- `search` string: Part of the e-mail, phone, first or last name, without case; % and _ are plain characters. Digits also match the id. To find a contact by its address, use `email`
- `created_since` string, date-time: `created_at` at or after this moment; without an offset, taken as UTC; a plain date means its start
- `created_before` string, date-time: `created_at` before this moment; without an offset, taken as UTC; a plain date means its start
- `updated_since` string, date-time: `updated_at` at or after this moment; without an offset, taken as UTC; a plain date means its start. Only contacts with a recorded change match
- `segment_id` integer: Matching the conditions of this segment, a segment id from `list_segments`
- `conditions` string: Matching a tree of conditions, as JSON: the language of `create_segment` `conditions`, without saving a segment; for example contacts without a first name: {"op": "and", "args": [{"op": "undefined", "args": ["{{$contact.firstName}}"]}]}

## Response `200`

Successful Response

- ContactsStatsTotal
  - `total` ContactCounts, required
    - `all` integer, required: The sum of the three statuses
    - `subscribed` integer, required: Subscribed, with double opt-in confirmed or not needed
    - `unsubscribed` integer, required: Unsubscribed, never subscribed or awaiting double opt-in
    - `bounced` integer, required: The address bounced or failed the e-mail check

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `segment_not_found`: no segment `segment_id` on the site
- `422`: `segment_conditions_invalid`: the conditions cannot be applied, the ones in `conditions` or the saved ones of the segment, which are fixed in the admin. `validation_failed`: a parameter is invalid
- `429`: `rate_limited`: a request limit is spent; this request also spends the heavy request limit
- `503`: `temporarily_unavailable`: the request took too long, or limits or idempotency keys cannot be enforced; narrow the filters or retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)