PRprivy
Segments

List segments

Changed on

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

get/segments

Request

  • Base URL
    https://api.privy.com/v1
  • Auth
    HTTP bearer

Query parameters

pageinteger

Page number (starts at 1).

per_pageinteger

Number of results per page. Values outside 10–100 are clamped to the nearest bound.

Headers

Privy-Account-Idstring

Target a subaccount instead of the main connected account. Pass a subaccount id from get_account's subaccounts list. Only direct subaccounts of the connected account are reachable — omit this for the main account itself.

Response

A paginated list of segments.

Example response

{
  "data": [
    {
      "id": "Rz5T2kW8pB",
      "name": "VIP Customers",
      "total_count": 1930,
      "mailable_count": 1240,
      "textable_count": 315,
      "counts": {
        "refreshed_at": "2026-06-15T08:00:00Z",
        "freshness": "Counts are refreshed periodically and may be up to an hour old."
      },
      "created_at": "2026-03-01T10:00:00Z",
      "updated_at": "2026-06-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total_count": 142,
    "total_pages": 6
  }
}

Changes

  • bc29b48dcdd2Revision changes
    • info

      added the optional property // to the response with the status

  • cf0885e90d5aRevision changes
    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new forbidden enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status

    • warning

      added the new segment_builder_required enum value to the / response property for the response status