---
title: "Get live segment counts"
method: GET
path: "/segments/{id}/counts"
tags: ["Segments"]
---

# Get live segment counts

`GET /segments/{id}/counts`

## Request

- Base URL: `https://api.privy.com/v1`
- URL: `https://api.privy.com/v1/segments/{id}/counts`
- Auth: HTTP bearer

How many contacts a saved segment reaches today. The counts on
`GET /v1/segments/{id}` are the ones its last membership refresh left
behind, dated by `counts.refreshed_at`, and they can lag or still be
zero after a create; this counts the segment's criteria against the
latest data now. It only reads, and saves and changes nothing. Each
count is a scan of the account's contacts, so it has its own budget
on top of the request limit: 20 per minute and 600 per UTC day for
each user, charged only when a count runs. A token with no user
shares one such budget per account.

Live counts need the account to be on the latest segment engine.
An account that is not yet is refused with
`403 live_counts_unavailable`: the merchant can ask Privy support to
migrate the account, and retrying does not help. An account whose
live answers Privy is checking is refused with
`403 live_counts_suspended`: the suspension lifts on its own within
a week, or sooner through Privy support, and retrying in the same
session does not help. The endpoint needs the account's new segment
builder, and answers `403 segment_builder_required` without it.
When live counts are paused or a count fails for the moment, the
answer is `503 counts_unavailable`; retry it after its `Retry-After`.
When a count runs out of time or memory, which an account's size can
make happen on every call, the answer is `422 counts_too_large`; Privy is
notified, and a retry does not help. When Privy cannot count the
saved criteria, the answer is `500 counts_failed`; Privy is notified,
and a plain retry rarely helps.
A saved condition the live engine cannot count as written, or that
reads all-time activity the account does not have, is
`422 segment_not_countable`: the segment's criteria are not the
request's to change, so read its refreshed counts instead.
A live count can differ from the refreshed one, and
from the members `GET /v1/segments/{id}/contacts` lists, until the
next refresh.

**Required scope:** `segments_read`

## Path parameters

- `id` string, required

## Headers

- `Privy-Account-Id` string

## Response `200`

The counts the conditions reach today.

- object
  - `data` object
    - `total_count` integer: Every matching contact, whether or not they can be reached.
    - `mailable_count` integer: Matching contacts who can be emailed.
    - `textable_count` integer: Matching contacts who can be texted.

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks `segments_read`, `live_counts_unavailable` when the account is not counted live, `live_counts_suspended` while its live answers are being checked, or `segment_builder_required` when the account does not yet have the new segment builder.
- `404`: The requested resource does not exist or does not belong to your account.
- `422`: `segment_not_countable` when a saved condition cannot be counted live as written, or reads all-time activity the account does not have (read the segment's refreshed counts instead), or `counts_too_large` when the count ran out of time or memory for this account (Privy is notified, and a retry does not help).
- `429`: Rate limit exceeded. Retry after the specified time.
- `500`: Privy could not count criteria that passed validation, or the live engine refused the query built from them. Privy is notified; a plain retry rarely helps.
- `503`: Live counts are paused or the count failed for the moment (`counts_unavailable`); `Retry-After` gives the seconds to wait before retrying.

## Changes

- **2026-11-05** `bc29b48dcdd2`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/segments/:id/counts/get.md)

---

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