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

# Get a segment

`GET /segments/{id}`

## Request

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

Retrieve a single segment by its identifier. The members themselves are
`/v1/segments/{id}/contacts`. A campaign's `audience` segment ids resolve
here when the segment was saved to the account. There is no per-segment performance report anywhere in the API.

**Required scope:** `segments_read`

## Path parameters

- `id` string, required

## Headers

- `Privy-Account-Id` string

## Response `200`

The segment.

- object
  - `data` SegmentDetail: A single segment, as returned by `GET /v1/segments/{id}`.
    - `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

## Other responses

- `401`: Missing or invalid bearer token.
- `403`: `insufficient_scope` when the token lacks the required scope for this endpoint.
- `404`: The requested resource does not exist or does not belong to your account.
- `429`: Rate limit exceeded. Retry after the specified time.

## Changes

- **2026-11-05** `bc29b48dcdd2`: 1 info
  - added the optional property `data/allOf[#/components/schemas/Segment]/total_count` to the response with the `200` status
- **2026-11-05** `cf0885e90d5a`: 8 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 `404`
  - added the new `forbidden` enum value to the `error/code` response property for the response status `429`
  - …4 more
- **2026-11-03** `fe500ab59b3b`: 1 info
  - endpoint added

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