---
title: "List segments"
method: GET
path: "/3.0/lists/{list_id}/segments"
tags: ["lists"]
---

# List segments

`GET /3.0/lists/{list_id}/segments`

## Request

- Base URL: `https://api.mailchimp.com`
- URL: `https://api.mailchimp.com/3.0/lists/{list_id}/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/lists/:list_id/segments/get.ts> (a function with typed inputs; its response is checked against the schema)

Get information about all available segments for a specific list.

## Path parameters

- `list_id` string, required

## Query parameters

- `fields` string[]
- `exclude_fields` string[]
- `count` integer
- `offset` integer
- `type` string
- `since_created_at` string
- `before_created_at` string
- `include_cleaned` boolean
- `include_transactional` boolean
- `include_unsubscribed` boolean
- `since_updated_at` string
- `before_updated_at` string
- `exclude_type` 'saved' | 'static' | 'fuzzy'

## Response `200`

- object: A list of available segments.
  - `_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.
  - `list_id` string: The list id.
  - `segments` object[]: An array of objects, each representing a list segment.
    - `_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.
    - `created_at` string, date-time: The date and time the segment was created in ISO 8601 format.
    - `id` integer: The unique id for the segment.
    - `list_id` string: The list id.
    - `member_count` integer: The number of active subscribers currently included in the segment.
    - `name` string: The name of the segment.
    - `options` object: The conditions of the segment. Static segments (tags) and fuzzy segments don't have conditions.
      - `conditions` union[]: Segment match conditions. There are multiple possible types, see the [condition types documentation](https://mailchimp.com/developer/marketing/docs/alternative-schemas/#segment-condition-schemas).
        - union
          - object: Segment by interaction with a specific campaign.
            - `condition_type` 'Aim'
            - `field` 'aim': Segment by interaction with a specific campaign.
            - `op` 'open' | 'click' | 'sent' | 'noopen' | 'noclick' | 'nosent': The status of the member with regard to their campaign interaction. One of the following: opened, clicked, was sent, didn't open, didn't click, or was not sent.
            - `value` string: Either the web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
          - object: Segment by interaction with an Automation workflow.
            - `condition_type` 'Automation'
            - `field` 'automation', required: Segment by interaction with an Automation workflow.
            - `op` 'started' | 'completed' | 'not_started' | 'not_completed', required: The status of the member with regard to the automation workflow. One of the following: has started the workflow, has completed the workflow, has not started the workflow, or has not completed the workflow.
            - `value` string, required: The web id for the automation workflow to segment against.
          - object: Segment by poll activity.
            - `condition_type` 'CampaignPoll'
            - `field` 'poll', required: Segment by poll activity.
            - `op` 'member' | 'notmember', required: Members have/have not interacted with a specific poll in a Mailchimp email.
            - `value` number, required: The id for the poll.
          - object: Segment by interaction with a campaign via Conversations.
            - `condition_type` 'Conversation'
            - `field` 'conversation', required: Segment by interaction with a campaign via Conversations.
            - `op` 'member' | 'notmember', required: The status of a member's interaction with a conversation. One of the following: has replied or has not replied.
            - `value` string, required: The web id value for a specific campaign or 'any' to account for subscribers who have/have not interacted with any campaigns.
          - object: Segment by a specific date field.
            - `condition_type` 'Date'
            - `extra` string: When segmenting on 'date' or 'campaign', the date for the segment formatted as YYYY-MM-DD or the web id for the campaign.
            - `field` 'timestamp_opt' | 'info_changed' | 'ecomm_date', required: The type of date field to segment on: The opt-in time for a signup, the date the subscriber was last updated, or the date of their last ecomm purchase.
            - `op` 'greater' | 'less' | 'is' | 'not' | 'blank' | 'blank_not' | 'within' | 'notwithin', required: When the event took place: Before, after, is a specific date, is not a specific date, is blank, or is not blank.
            - `value` string, required: What type of data to segment on: a specific date, a specific campaign, or the last campaign sent.
          - object: Segment by use of a particular email client.
            - `condition_type` 'EmailClient'
            - `field` 'email_client', required: Segment by use of a particular email client.
            - `op` 'client_is' | 'client_not', required: The operation to determine whether we select clients that match the value, or clients that do not match the value.
            - `value` string, required: The name of the email client.
          - object: Segment by language.
            - `condition_type` 'Language'
            - `field` 'language', required: Segmenting based off of a subscriber's language.
            - `op` 'is' | 'not', required: Whether the member's language is or is not set to a specific language.
            - `value` string, required: A two-letter language identifier.
          - object: Segment by member rating.
            - `condition_type` 'MemberRating'
            - `field` 'rating', required: Segment by member rating.
            - `op` 'is' | 'not' | 'greater' | 'less', required: Members who have have a rating that is/not exactly a given number or members who have a rating greater/less than a given number.
            - `value` union, required
              - …
          - object: Segment by signup source.
            - `condition_type` 'SignupSource', required
            - `field` 'source', required
            - `op` 'source_is' | 'source_not', required: Whether the member's signup source was/was not a particular value.
            - `value` string: The signup source.
          - object: Segment by interaction with a SurveyMonkey survey.
            - `condition_type` 'SurveyMonkey'
            - `field` 'survey_monkey', required: Segment by interaction with a SurveyMonkey survey.
            - `op` 'started' | 'completed' | 'not_started' | 'not_completed', required: The status of the member with regard to the survey.One of the following: has started the survey, has completed the survey, has not started the survey, or has not completed the survey.
            - `value` string, required: The unique ID of the survey monkey survey.
          - object: Segment by VIP status.
            - `condition_type` 'VIP'
            - `field` 'gmonkey', required: Segment by VIP status.
            - `op` 'member' | 'notmember', required: Whether the member is or is not marked as VIP.
          - object: Segment by an interest group merge field.
            - `condition_type` 'Interests'
            - `field` string: Segmenting based on interest group information. This should start with 'interests-' followed by the grouping id. Ex. 'interests-123'.
            - `op` 'interestcontains' | 'interestcontainsall' | 'interestnotcontains': Whether the member is a part of one, all, or none of the groups.
            - `value` string[]: An array containing strings, each representing a group id.
          - object: Segment by purchases in specific items or categories.
            - `condition_type` 'EcommCategory'
            - `field` 'ecomm_cat' | 'ecomm_prod': Segment by purchases in specific items or categories.
            - `op` 'is' | 'not' | 'contains' | 'notcontain' | 'starts' | 'ends': A member who has purchased from a category/specific item that is/is not a specific name, where the category/item name contains/doesn't contain a specific phrase or string, or a category/item name that starts/ends with a string.
            - `value` string: The ecommerce category/item information.
          - object: Segment by average spent total, number of orders, total number of products purchased, or average number of products per order.
            - `condition_type` 'EcommNumber'
            - `field` 'ecomm_spent_avg' | 'ecomm_orders' | 'ecomm_prod_all' | 'ecomm_avg_ord', required: Segment by average spent total, number of orders, total number of products purchased, or average number of products per order.
            - `op` 'is' | 'not' | 'greater' | 'less', required: Members who have spent exactly, have not spent exactly, spent more, or spent less than the segment value.
            - `value` union, required
              - …
          - object: Segment by whether someone has purchased anything.
            - `condition_type` 'EcommPurchased'
            - `field` 'ecomm_purchased': Segment by whether someone has purchased anything.
            - `op` 'member' | 'notmember': Members who have have ('member') or have not ('notmember') purchased.
          - object: Segment by amount spent on a single order or across all orders.
            - `condition_type` 'EcommSpent'
            - `field` 'ecomm_spent_one' | 'ecomm_spent_all': Segment by amount spent on a single order or across all orders.
            - `op` 'greater' | 'less': Members who have spent 'more' or 'less' than then specified value.
            - `value` union
              - …
          - object: Segment by purchases from a specific store.
            - `condition_type` 'EcommStore'
            - `field` 'ecomm_store': Segment by purchases from a specific store.
            - `op` 'is' | 'not': Members who have or have not purchased from a specific store.
            - `value` string: The store id to segment against.
          - object: Segment by Goal activity.
            - `condition_type` 'GoalActivity'
            - `field` 'goal', required: Segment by Goal activity.
            - `op` 'is' | 'goal_not' | 'contains' | 'goal_notcontain' | 'starts' | 'ends', required: Whether the website URL is/not exactly, contains/doesn't contain, starts with/ends with a string.
            - `value` string, required: The URL to check Goal activity against.
          - object: Segment by most recent interaction with a website.
            - `condition_type` 'GoalTimestamp'
            - `field` 'goal_last_visited', required: Segment by most recent interaction with a website.
            - `op` 'greater' | 'less' | 'is', required: Whether the website activity happened after, before, or at a given timestamp.
            - `value` string, required: The date to check Goal activity against.
          - object: Segment by similar subscribers.
            - `condition_type` 'FuzzySegment'
            - `field` 'fuzzy_segment', required: Segment by similar subscribers.
            - `op` 'fuzzy_is' | 'fuzzy_not', required: Members who are/are not apart of a 'similar subscribers' segment.
            - `value` union, required
              - …
          - object: Segment by a given static segment.
            - `condition_type` 'StaticSegment'
            - `field` 'static_segment', required: Segment by a given static segment.
            - `op` 'static_is' | 'static_not', required: Members who are/are not apart of a static segment.
            - `value` union, required
              - …
          - object: Segment by a specific country or US state.
            - `condition_type` 'IPGeoCountryState'
            - `field` 'ipgeo', required: Segmenting subscribers who are within a specific location.
            - `op` 'ipgeocountry' | 'ipgeonotcountry' | 'ipgeostate' | 'ipgeonotstate', required: Segment members who are within a specific country or US state.
            - `value` string, required: The two-letter country code or US state abbreviation.
          - object: Segment by a specific geographic region.
            - `addr` string, required: The address of the target location.
            - `condition_type` 'IPGeoIn'
            - `field` 'ipgeo', required: Segmenting subscribers who are within a specific location.
            - `lat` string, required: The latitude of the target location.
            - `lng` string, required: The longitude of the target location.
            - `op` 'ipgeoin' | 'ipgeonotin', required: Segment members who are within a specific geographic region.
            - `value` integer, required: The radius of the target location.
          - object: Segment by a specific US ZIP code.
            - `condition_type` 'IPGeoInZip'
            - `extra` integer, required: The zip code to segment against.
            - `field` 'ipgeo', required: Segmenting subscribers who are within a specific location.
            - `op` 'ipgeoinzip', required: Segment members who are within a specific US zip code.
            - `value` integer, required: The radius of the target location.
          - object: Segment members whose location information is unknown.
            - `condition_type` 'IPGeoUnknown'
            - `field` 'ipgeo', required: Segmenting subscribers who are within a specific location.
            - `op` 'ipgeounknown', required: Segment members for which location information is unknown.
          - object: Segment by a specific US ZIP code.
            - `condition_type` 'IPGeoZip'
            - `field` 'ipgeo', required: Segmenting subscribers who are within a specific location.
            - `op` 'ipgeoiszip' | 'ipgeonotzip', required: Segment members who are/are not within a specific US zip code.
            - `value` integer, required: The 5-digit zip code.
          - object: Segment by age ranges in Social Profiles data.
            - `condition_type` 'SocialAge'
            - `field` 'social_age', required: Segment by age ranges in Social Profiles data.
            - `op` 'is' | 'not', required: Members who are/not the exact criteria listed.
            - `value` '18-24' | '25-34' | '35-54' | '55+', required: The age range to segment.
          - object: Segment by listed gender in Social Profiles data.
            - `condition_type` 'SocialGender'
            - `field` 'social_gender', required: Segment by listed gender in Social Profiles data.
            - `op` 'is' | 'not', required: Members who are/not the exact criteria listed.
            - `value` 'male' | 'female', required: The Social Profiles gender to segment.
          - object: Segment by influence rating in Social Profiles data.
            - `condition_type` 'SocialInfluence'
            - `field` 'social_influence', required: Segment by influence rating in Social Profiles data.
            - `op` 'is' | 'not' | 'greater' | 'less', required: Members who have a rating that is/not or greater/less than the rating provided.
            - `value` number, required: The Social Profiles influence rating to segment.
          - object: Segment by social network in Social Profiles data.
            - `condition_type` 'SocialNetworkMember'
            - `field` 'social_network', required: Segment by social network in Social Profiles data.
            - `op` 'member' | 'notmember', required: Members who are/not on a given social network.
            - `value` 'twitter' | 'facebook' | 'linkedin' | 'flickr' | 'foursquare' | 'lastfm' | 'myspace' | 'quora' | 'vimeo' | 'yelp' | 'youtube', required: The social network to segment against.
          - object: Segment by social network in Social Profiles data.
            - `condition_type` 'SocialNetworkFollow'
            - `field` 'social_network', required: Segment by social network in Social Profiles data.
            - `op` 'follow' | 'notfollow', required: Members who are/not following a linked account on a given social network.
            - `value` 'twitter_follow', required: The social network to segment against.
          - object: Segment by an address-type merge field.
            - `condition_type` 'AddressMerge'
            - `field` string, required: An address-type merge field to segment.
            - `op` 'contains' | 'notcontain' | 'blank' | 'blank_not', required: Whether the member's address merge field contains/does not contain a value or is/is not blank.
            - `value` string: The value to segment a text merge field with.
          - object: Segment by an address-type merge field within a given distance.
            - `condition_type` 'ZipMerge'
            - `extra` string, required: The city or the zip being used to segment against.
            - `field` string, required: An address or zip-type merge field to segment.
            - `op` 'geoin', required: Whether the member's address merge field is within a given distance from a city or zip.
            - `value` string, required: The distance from the city/zip.
          - object: Segment by a contact's birthday.
            - `condition_type` 'BirthdayMerge'
            - `field` string, required: A date merge field to segment.
            - `op` 'is' | 'not' | 'blank' | 'blank_not', required: Whether the member's birthday merge information is/is not a certain date or is/is not blank.
            - `value` string: A date to segment against (mm/dd).
          - object: Segment by a given date merge field.
            - `condition_type` 'DateMerge'
            - `field` string, required: A date merge field to segment.
            - `op` 'is' | 'not' | 'less' | 'blank' | 'blank_not' | 'greater', required: Whether the member's merge information is/is not, is greater/less than a value or is/is not blank.
            - `value` string: A date to segment against.
          - object: An individual segment condition
            - `condition_type` 'SelectMerge'
            - `field` string, required: A merge field to segment.
            - `op` 'is' | 'not' | 'blank' | 'blank_not' | 'notcontain' | 'contains', required: Whether the member's merge information is/is not a value or is/is not blank.
            - `value` string: The value to segment a text merge field with.
          - object: Segment by a given text or number merge field.
            - `condition_type` 'TextMerge'
            - `field` string, required: A text or number merge field to segment.
            - `op` 'is' | 'not' | 'contains' | 'notcontain' | 'starts' | 'ends' | 'greater' | 'less' | 'blank' | 'blank_not', required: Whether the member's merge information is/is not, contains/does not contain, starts/ends with, or is greater/less than a value
            - `value` string: The value to segment a text or number merge field with.
          - object: Segment by email address.
            - `condition_type` 'EmailAddress'
            - `field` 'merge0' | 'EMAIL', required: Segmenting based off of a subscriber's email address.
            - `op` 'is' | 'not' | 'contains' | 'notcontain' | 'starts' | 'ends' | 'greater' | 'less', required: Whether the email address is/not exactly, contains/doesn't contain, starts/ends with a string.
            - `value` string: The value to compare the email against.
          - object: Segment by predicted gender.
            - `condition_type` 'PredictedGender'
            - `field` 'predicted_gender', required: Segment by predicted gender.
            - `op` 'is' | 'not', required: Members who are/not the exact criteria listed.
            - `value` 'male' | 'female', required: The predicted gender to segment.
          - object: Segment by predicted age.
            - `condition_type` 'PredictedAge'
            - `field` 'predicted_age_range', required: Segment by predicted age.
            - `op` 'is', required: Members who are/not the exact criteria listed.
            - `value` '18-24' | '25-34' | '35-44' | '45-54' | '55-64' | '65+', required: The predicted age to segment.
          - object: Segment by when people subscribed.
            - `condition_type` 'NewSubscribers'
            - `field` 'timestamp_opt': Segment by when people subscribed.
            - `op` 'date_within': Whe the event took place, namely within a time frame.
            - `value` string: What type of data to segment on: a specific date, a specific campaign, or the last campaign sent.
      - `match` 'any' | 'all': Match type.
    - `type` 'saved' | 'static' | 'fuzzy': The type of segment. Static segments are now known as tags. Learn more about [tags](https://mailchimp.com/help/getting-started-tags?utm_source=mc-api&utm_medium=docs&utm_campaign=apidocs).
    - `updated_at` string, date-time: The date and time the segment was last updated in ISO 8601 format.
  - `total_items` integer: The total number of items matching the query regardless of pagination.

## 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)