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

# List Segments

`GET /3.0/segments`

## Request

- Base URL: `https://api.mailchimp.com`
- URL: `https://api.mailchimp.com/3.0/segments`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://login.mailchimp.com/oauth2/authorize`
    - Token URL: `https://login.mailchimp.com/oauth2/token`
- TypeScript: <https://skmtc.dev/mailchimp/apis/mailchimp-api/docs/3.0/segments/get.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Query parameters

- `fields` string[]
- `exclude_fields` string[]
- `count` integer
- `cursor` string
- `list_id` string, required
- `sort_field` 'created_at' | 'name'
- `sort_dir` 'ASC' | 'DESC'

## Response `200`

- object: A list of segments. Each segment contains only its metadata.
  - `_links` object[]: A list of link types and descriptions for the API schema documents.
    - `href` string: This property contains a fully-qualified URL that can be called to retrieve the linked resource or perform the linked action.
    - `method` 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD': The HTTP method that should be used when accessing the URL defined in 'href'.
    - `rel` string: As with an HTML 'rel' attribute, this describes the type of link.
    - `schema` string: 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: For GETs, this is a URL representing the schema that the response should conform to.
  - `next_cursor` string: 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` object[]: The segments of the list. The `read_only` property of each segment shows if you can update it.
    - `created_at` string, date-time: The date and time when Mailchimp created the segment, in ISO 8601 format.
    - `id` string, uuid: The unique ID of the segment. Do not parse or change this value. Use it exactly as you received it.
    - `list_id` string: The unique ID of the list that contains the segment.
    - `read_only` boolean: 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: The name of the segment.
  - `total_items` integer: The total number of segments that match the request. It does not change with `count` or `cursor`.

## Other responses

- `default`: An error generated by the Mailchimp API.

---

[API](https://skmtc.dev/mailchimp/apis/mailchimp-api.md) - [All operations](https://skmtc.dev/mailchimp/apis/mailchimp-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mailchimp/apis/mailchimp-api/revisions/53bf4b156855?raw)