---
title: "List segments"
method: GET
path: "/segments"
tags: ["Segments"]
---

# List segments

`GET /segments`

## Request

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

Retrieve a paginated list of your customer segments with their mailable/textable member counts.

Rows carry each segment's name, prebuilt flag, and reachable-member counts
but not its members: `/v1/segments/{id}/contacts` returns them. Nothing in the API
reports performance per segment — there is no segment report, so revenue
or engagement for a segment cannot be answered from here.

**Required scope:** `segments_read`

## Query parameters

- `page` integer
- `per_page` integer

## Headers

- `Privy-Account-Id` string

## Response `200`

A paginated list of segments.

- object
  - `data` Segment[]
    - `id` string: Stable, unique identifier for the segment. Use this value in `/v1/segments/{id}`.
    - `name` string
    - `prebuilt` boolean: Whether the segment was created from one of Privy's prebuilt smart segment templates. (All segments are dynamic — membership is computed from criteria, not a static list — so there is no `type` field.)
    - `total_count` integer, nullable: Number of members whatever their consent state, as of `counts.refreshed_at`. `null` if never computed.
    - `mailable_count` integer, nullable: Number of members reachable by email, as of `counts.refreshed_at`. `null` if never computed.
    - `textable_count` integer, nullable: Number of members reachable by SMS, as of `counts.refreshed_at`. `null` if never computed.
    - `counts` object
      - `recounting` boolean: Whether a membership refresh is currently running.
      - `refreshed_at` string, date-time, nullable: When membership and counts were last computed. `null` if never computed.
      - `freshness` string: Note on how current the counts are.
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `pagination` PaginationEnvelope
    - `page` integer
    - `per_page` integer
    - `total_count` integer
    - `total_pages` integer

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `bc29b48dcdd2`: 1 info
  - added the optional property `data/items/total_count` to the response with the `200` status
- **2026-11-05** `cf0885e90d5a`: 6 warning
  - added the new `forbidden` enum value to the `error/code` response property for the response status `401`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `403`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - added the new `segment_builder_required` enum value to the `error/code` response property for the response status `401`
  - …2 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/privy/apis/privy-api/changes/segments/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)