Get a list of all segments for an account.

Use the GET segments/ endpoint to get a list of all segments in an account and details about each segment. The following shows the type of details returned in the response body for each segment and provides property descriptions.

   "name": "Non-openers",
   "segment_id": 30,
   "created_at": "2020-01-24T17:08:32.000Z",
   "edited_at": "2020-01-27T17:10:50.000Z"
name stringThe unique name that you specify for a segment.
segment_idintegerThe system generated ID that uniquely identifies a segment.
created_atstring The system generated date and time that the segment was created. The read-only date and time displays in ISO-8601 format.
edited_atstringThe system generated date and time that the segment's name or segment_criteria was last edited. The read-only date and time displays in ISO-8601 format.

Segment criteria and deleted segments are not returned in the segment response body. To view the segment_criteria for a single segment, use the GET segments/{segment_id} endpoint.

Authorization Requirements

User privileges: contacts:lists:read

Authorization scopes: contact_data


Use the limit parameter to specify the number of segments that you want returned on each page. The default number of segments to return is 1000 per page. Segments can be sorted in descending date order using sort_by=date or in ascending order using the segment sort_by=name. The default sort order is by descending date with the most recently updated segments listed first.

If no segments exist for the account, a 200 response is returned with an empty array.

Example GET Segments Request

The following GET /segments request uses the limit parameter to return 3 segments per page of results.


 $request = new HttpRequest();
   'limit' => '3'
   'cache-control' => 'no-cache',
   'Connection' => 'keep-alive',
   'Accept-Encoding' => 'gzip, deflate',
   'Host' => '',
   'Cache-Control' => 'no-cache',
   'Authorization' => 'Bearer {access_token}',
   'Content-Type' => 'application/json',
   'Accept' => '*/*'
 try {
   $response = $request->send();
   echo $response->getBody();
 } catch (HttpException $ex) {
   echo $ex;
curl -X GET \' \
  -H 'Accept: */*' \
  -H 'Accept-Encoding: gzip, deflate' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Cache-Control: no-cache' \
  -H 'Connection: keep-alive' \
  -H 'Content-Type: application/json' \
  -H 'Host:' \
  -H 'cache-control: no-cache'
OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .addHeader("Accept", "*/*")
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {access_token}")
  .addHeader("Cache-Control", "no-cache")
  .addHeader("Host", "")
  .addHeader("Accept-Encoding", "gzip, deflate")
  .addHeader("Connection", "keep-alive")
  .addHeader("cache-control", "no-cache")

Response response = client.newCall(request).execute();


     "segments": [
             "name": "Non-openers",
             "segment_id": 30,
             "created_at": "2020-01-24T17:08:32.000Z",
             "edited_at": "2020-01-27T17:10:50.000Z"
             "name": "Opened any of my the last 7 campaigns",
             "segment_id": 28,
             "created_at": "2020-01-22T17:01:10.000Z",
             "edited_at": "2020-01-22T17:01:10.000Z"
             "name": "Opened any of my the last 14 campaigns",
             "segment_id": 27,
             "created_at": "2020-01-21T15:25:52.000Z",
             "edited_at": "2020-01-21T15:25:52.000Z"
      "_links": {
          "next": {
              "href": "/v1/accounts/1100560563333/segments/?next=c29ydF92YWx1ZT0yMDIwLTAxLTE3IDE5OjQwOjQwJmxpbWl0PTMmc29ydF9ieT1kYXRl"

Try it!