---
title: "Get list info"
method: GET
path: "/3.0/lists/{list_id}"
tags: ["lists"]
---

# Get list info

`GET /3.0/lists/{list_id}`

## Request

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

Get information about a specific list in your Mailchimp account. Results include list members who have signed up but haven't confirmed their subscription yet and unsubscribed or cleaned.

## Path parameters

- `list_id` string, required

## Query parameters

- `fields` string[]
- `exclude_fields` string[]
- `include_total_contacts` boolean

## Response `200`

- object: Information about a specific list.
  - `_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.
  - `beamer_address` string: The list's [Email Beamer](https://mailchimp.com/help/use-email-beamer-to-create-a-campaign/) address.
  - `campaign_defaults` object: [Default values for campaigns](https://mailchimp.com/help/edit-your-emails-subject-preview-text-from-name-or-from-email-address/) created for this list.
    - `from_email` string: The default from email for campaigns sent to this list.
    - `from_name` string: The default from name for campaigns sent to this list.
    - `language` string: The default language for this lists's forms.
    - `subject` string: The default subject line for campaigns sent to this list.
  - `contact` object: [Contact information displayed in campaign footers](https://mailchimp.com/help/about-campaign-footers/) to comply with international spam laws.
    - `address1` string: The street address for the list contact.
    - `address2` string: The street address for the list contact.
    - `city` string: The city for the list contact.
    - `company` string: The company name for the list.
    - `country` string: A two-character ISO3166 country code. Defaults to US if invalid.
    - `phone` string: The phone number for the list contact.
    - `state` string: The state for the list contact.
    - `zip` string: The postal or zip code for the list contact.
  - `date_created` string, date-time: The date and time that this list was created in ISO 8601 format.
  - `double_optin` boolean: Whether or not to require the subscriber to confirm subscription via email.
  - `email_type_option` boolean: Whether the list supports [multiple formats for emails](https://mailchimp.com/help/audience-settings-and-defaults/). When set to `true`, subscribers can choose whether they want to receive HTML or plain-text emails. When set to `false`, subscribers will receive HTML emails, with a plain-text alternative backup.
  - `has_welcome` boolean: Whether or not this list has a welcome automation connected. Welcome Automations: welcomeSeries, singleWelcome, emailFollowup.
  - `id` string: A string that uniquely identifies this list.
  - `list_rating` integer: An auto-generated activity score for the list (0-5).
  - `marketing_permissions` boolean: Whether or not the list has marketing permissions (eg. GDPR) enabled.
  - `modules` string[]: Any list-specific modules installed for this list.
  - `name` string: The name of the list.
  - `notify_on_subscribe` string: The email address to send [subscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
  - `notify_on_unsubscribe` string: The email address to send [unsubscribe notifications](https://mailchimp.com/help/change-subscribe-and-unsubscribe-notifications/) to.
  - `permission_reminder` string: The [permission reminder](https://mailchimp.com/help/edit-the-permission-reminder/) for the list.
  - `stats` object: Stats for the list. Many of these are cached for at least five minutes.
    - `avg_sub_rate` number: The average number of subscriptions per month for the list (not returned if we haven't calculated it yet).
    - `avg_unsub_rate` number: The average number of unsubscriptions per month for the list (not returned if we haven't calculated it yet).
    - `campaign_count` integer: The number of campaigns in any status that use this list.
    - `campaign_last_sent` string, date-time: The date and time the last campaign was sent to this list in ISO 8601 format. This is updated when a campaign is sent to 10 or more recipients.
    - `cleaned_count` integer: The number of members cleaned from the list.
    - `cleaned_count_since_send` integer: The number of members cleaned from the list since the last campaign was sent.
    - `click_rate` number: The average click rate (a percentage represented as a number between 0 and 100) per campaign for the list (not returned if we haven't calculated it yet).
    - `last_sub_date` string, date-time: The date and time of the last time someone subscribed to this list in ISO 8601 format.
    - `last_unsub_date` string, date-time: The date and time of the last time someone unsubscribed from this list in ISO 8601 format.
    - `member_count` integer: The number of active members in the list.
    - `member_count_since_send` integer: The number of active members in the list since the last campaign was sent.
    - `merge_field_count` integer: The number of merge fields ([audience field](https://mailchimp.com/help/getting-started-with-merge-tags/)) for this list (doesn't include EMAIL).
    - `open_rate` number: The average open rate (a percentage represented as a number between 0 and 100) per campaign for the list (not returned if we haven't calculated it yet).
    - `target_sub_rate` number: The target number of subscriptions per month for the list to keep it growing (not returned if we haven't calculated it yet).
    - `total_contacts` integer: An approximate count of subscribed, unsubscribed, and transactional contacts in the list. Does not include cleaned, archived, pending, or contacts that need to be reconfirmed. Requires the (deprecated) include_total_contacts query parameter to be included; for a complete audience contact count, use the /audiences endpoint instead.
    - `unsubscribe_count` integer: The number of members who have unsubscribed from the list.
    - `unsubscribe_count_since_send` integer: The number of members who have unsubscribed since the last campaign was sent.
  - `subscribe_url_long` string: The full version of this list's subscribe form (host will vary).
  - `subscribe_url_short` string: Our [url shortened](https://mailchimp.com/help/share-your-signup-form/) version of this list's subscribe form.
  - `use_archive_bar` boolean: Whether campaigns for this list use the [Archive Bar](https://mailchimp.com/help/about-email-campaign-archives-and-pages/) in archives by default.
  - `visibility` 'pub' | 'prv': Legacy - visibility settings are no longer used
  - `web_id` integer: The ID used in the Mailchimp web application. View this list in your Mailchimp account at `https://{dc}.admin.mailchimp.com/lists/members/?id={web_id}`.

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