> This page is for Mailchimp Marketing API.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://mailchimp.com/developer/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://mailchimp.com/developer/_mcp/server.

# List Segments

GET https://api.mailchimp.com/3.0/segments

Get the segments of a list. The response contains only metadata. It includes advanced segments and read-only segments that other Mailchimp tools made, for example Google Analytics segments and segments from the AI segment builder. The `read_only` property of each segment shows if you can update it.

Reference: https://mailchimp.com/developer/marketing/api/segments/get-segment-list

## Authentication

- `Authorization` header (bearer token, required) — Authorization using a Mailchimp API key (a.k.a. Bearer token)
- `Authorization` header (bearer token, required) — Authorization using OAuth

## Request

### Query parameters

- `fields` (list of string, optional) — A comma-separated list of fields to return. Reference parameters of sub-objects with dot notation.
- `exclude_fields` (list of string, optional) — A comma-separated list of fields to exclude. Reference parameters of sub-objects with dot notation.
- `count` (integer, optional, default: 10) — The number of segments to return. The default is 10. Use a whole number from 1 to 1000. If you use a different value, the API returns a 400 error. The API does not change the value.
- `cursor` (string, optional) — To get the next page of segments, set `cursor` to the `next_cursor` value from the previous response. Do not make or change a cursor value. If you do, pagination can stop without notice. To get the first page, do not include `cursor`. If a response does not contain `next_cursor`, there are no more pages. If segments are created or deleted while you get the pages, the response can skip or repeat a segment.
- `list_id` (string, required) — The unique ID of the list to get segments from.
- `sort_field` (enum, optional) — The field to sort the segments by.
  - Allowed values: `created_at`, `name`
- `sort_dir` (enum, optional, default: DESC) — The sort direction. The default is DESC. Use ASC or DESC. The value is not case-sensitive. If you use a different value, the API returns a 400 error.
  - Allowed values: `ASC`, `DESC`

## Response

### 200

- `_links` (list of 30SegmentsGetResponsesContentApplicationJsonSchemaLinksItems, optional) — A list of link types and descriptions for the API schema documents.
- `next_cursor` (string, optional) — A cursor pointing to the last item on this page of the collection. Paginate through a collection of records by setting the `cursor` parameter on a subsequent request to this value.
- `segments` (list of 30SegmentsGetResponsesContentApplicationJsonSchemaSegmentsItems, optional) — The segments of the list. The `read_only` property of each segment shows if you can update it.

## Types

### 30SegmentsGetResponsesContentApplicationJsonSchemaLinksItems

This object represents a link from the resource where it is found to another resource or action that may be performed.

- `href` (string, optional) — This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
- `method` (enum, optional) — The HTTP method that should be used when accessing the URL defined in 'href'.
  - Allowed values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `OPTIONS`, `HEAD`
- `rel` (string, optional) — As with an HTML 'rel' attribute, this describes the type of link.
- `schema` (string, optional) — For HTTP methods that can receive bodies (POST and PUT), this is a URL representing the schema that the body should conform to.
- `targetSchema` (string, optional) — For GETs, this is a URL representing the schema that the response should conform to.

### 30SegmentsGetResponsesContentApplicationJsonSchemaSegmentsItems

The metadata of a segment in the segment list. It does not include the `definition` or a member count. In this API version, Mailchimp does not change or remove existing fields, but Mailchimp can add new fields. Make sure that your client ignores fields that it does not know.

- `created_at` (datetime, optional) — The date and time when Mailchimp created the segment, in ISO 8601 format.
- `id` (string, optional) — The unique ID of the segment. Do not parse or change this value. Use it exactly as you received it.
- `list_id` (string, optional) — The unique ID of the list that contains the segment.
- `read_only` (boolean, optional) — If true, you can read, count, and snapshot the segment, but you cannot update or delete it. Segments that other Mailchimp tools made, for example Google Analytics segments, are read-only. A read-only segment does not have a definition.
- `name` (string, optional) — The name of the segment.

## Examples

**Response**

```json
{
  "_links": [
    {
      "href": "string",
      "method": "GET",
      "rel": "string",
      "schema": "string",
      "targetSchema": "string"
    }
  ],
  "next_cursor": "string",
  "segments": [
    {
      "created_at": "2025-01-15T10:30:00+00:00",
      "id": "0dbaba26-0003-8000-8000-000000000919",
      "list_id": "a1b2c3d4e5",
      "read_only": true,
      "name": "Example Segment"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.mailchimp.com/3.0/segments"

querystring = {"list_id":"list_id"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.mailchimp.com/3.0/segments?list_id=list_id';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mailchimp.com/3.0/segments?list_id=list_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.mailchimp.com/3.0/segments?list_id=list_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.mailchimp.com/3.0/segments?list_id=list_id")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.mailchimp.com/3.0/segments?list_id=list_id', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.mailchimp.com/3.0/segments?list_id=list_id");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mailchimp.com/3.0/segments?list_id=list_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```