Sign in

v2

latestOpenAPI 3.1.12026-07-2613060964.2 KB

Get List configuration

API to fetch list metadata like list type, count, source, and status. Doesn't include users in the list. For Segment Lists (list_type: dynamic_list), the response also includes the committed query and the sync_task block with the live version.

get/v1/subscriber_list/{list_id}/

Path parameters

list_idstring required

Unique string identifier of the list.

Response

200

list_idstring

Unique identifier of the list.

list_namestring

Name of the list.

list_descriptionstring

Brief description of the list.

list_type'static_list' | 'dynamic_list'

Type of the list.

subscribers_countinteger

number of users in the list

sourcestring

source info on how the list is updated

is_readonlyboolean

Indicates whether the list is read-only.

is_enabledboolean

For dynamic_list only. Whether the segment is actively refreshing.

querystring

For dynamic_list only. The committed SQL query that defines the segment.

statusstring

Current status of the list (active or draft).

track_user_entryboolean

Event $USER_ENTERED_LIST - <list_id> is generated when user is added this list. Use this to trigger workflow on user entry.

track_user_exitboolean

Event $USER_EXITED_LIST - <list_id> is generated when user is removed from this list. Use this to trigger workflow on user exit.

requested_for_deleteboolean

Indicates whether the list has been requested for deletion.

created_atstring date-time

Timestamp when the list was created.

updated_atstring date-time

Timestamp when the list was last updated.

draftsstring nullable

would show the draft list created to replace list users.

Example response

{
  "list_id": "product_updates",
  "list_name": "Product Update",
  "list_description": "Users subscribed to the newsletter",
  "source": "database_sync",
  "is_enabled": true,
  "query": "SELECT distinct_id FROM users WHERE CAST(user_properties ->> 'lifetime_value' AS DOUBLE PRECISION) >= 2500",
  "status": "active",
  "created_at": "2024-02-21T19:10:01.906000Z",
  "updated_at": "2025-04-04T07:25:43.186475Z"
}