> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voyantcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Members

> Retrieve members of a marketing list with optional filtering.

## Method

`GET` `/v1/comms/lists/:id/members`

## Path Parameters

<ParamField path="id" type="string" required>The list ID.</ParamField>

## Query Parameters

<ParamField query="status" type="string">Filter by member status (`subscribed`, `unsubscribed`, `cleaned`, `bounced`).</ParamField>
<ParamField query="limit" type="number">Maximum number of results (1-100, default 50).</ParamField>
<ParamField query="offset" type="number">Number of results to skip for pagination (default 0).</ParamField>

## Headers

<ParamField header="Authorization" type="string" required>Bearer token (requires `comms:read`).</ParamField>

## Request Example

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.voyantcloud.com/v1/comms/lists/lists_01J0CBFPXW7SP2N8A9Q7T2048Q/members?status=subscribed" \
    -H "Authorization: Bearer $VOYANT_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const listId = "lists_01J0CBFPXW7SP2N8A9Q7T2048Q"
  const res = await fetch(
    `https://api.voyantcloud.com/v1/comms/lists/${listId}/members?status=subscribed`,
    {
      headers: { Authorization: `Bearer ${process.env.VOYANT_API_KEY}` },
    }
  )
  const { items, meta } = await res.json()
  ```

  ```python Python theme={null}
  import os, requests

  list_id = "lists_01J0CBFPXW7SP2N8A9Q7T2048Q"
  resp = requests.get(
    f"https://api.voyantcloud.com/v1/comms/lists/{list_id}/members",
    params={"status": "subscribed"},
    headers={"Authorization": f"Bearer {os.environ['VOYANT_API_KEY']}"},
  )
  members = resp.json()["items"]
  ```
</RequestExample>

## Response Fields

Each member item includes:

* `id` – Member ID.
* `list_id` – List ID.
* `person_id` – Person ID.
* `status` – Member status (`subscribed`, `unsubscribed`, `cleaned`, `bounced`).
* `source` – How the member was added (`manual`, `import`, `api`, `form`).
* `subscribed_at` – When the member subscribed.
* `unsubscribed_at` – When the member unsubscribed (if applicable).
* `created_at` – ISO timestamp.
* `person` – Person details (id, first\_name, last\_name, email).

## Response Example

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "items": [
      {
        "id": "list_members_01J0CBFPXW7SP2N8A9Q7T2048Q",
        "list_id": "lists_01J0CBFPXW7SP2N8A9Q7T2048Q",
        "person_id": "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
        "status": "subscribed",
        "source": "api",
        "subscribed_at": "2025-01-08T10:22:31.000Z",
        "unsubscribed_at": null,
        "created_at": "2025-01-08T10:22:31.000Z",
        "person": {
          "id": "people_01HZYPM2QF2R8X9SZQ0J9SYBCN",
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com"
        }
      }
    ],
    "meta": {
      "total": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": "List not found"
  }
  ```
</ResponseExample>