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"
}

Changes

Changed in 3 of the 7 revisions of this API.136

Aug 20, 20269a5a2cd152ae1See the full diff
- ▲
  added the pattern ^[a-z0-9_-]+$ to the path request parameter list_id
  request-parameter-pattern-added
Aug 10, 2026a686fddb4e0c22See the full diff
- ●
  removed the optional property sync_task/active_version/query_text from the response with the 200 status
  response-optional-property-removed
- ●
  removed the optional property sync_task/draft_version/query_text from the response with the 200 status
  response-optional-property-removed
- ○
  added the optional property sync_task/active_version/query to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property sync_task/draft_version/query to the response with the 200 status
  response-optional-property-added
Jul 26, 20268bd2574bd2c314See the full diff
- ●
  added the new dynamic_list enum value to the list_type response property for the response status 200
  response-property-enum-value-added
- ○
  added the optional property is_enabled to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property query to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property sync_task to the response with the 200 status
  response-optional-property-added
- ○
  removed the query_based enum value from the list_type response property for the response status 200
  response-property-enum-value-removed

Full history