> ## 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 Marketing Lists

> Retrieve all marketing lists in the workspace with optional filtering.

## Method

`GET` `/v1/comms/lists`

## Query Parameters

<ParamField query="source" type="string">Filter by list source (`manual`, `import`, `signup_form`, `api`).</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?limit=10" \
    -H "Authorization: Bearer $VOYANT_API_KEY"
  ```

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

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

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

## Response Fields

Each list item includes:

* `id` – List ID.
* `workspace_id` – Workspace owning the list.
* `name` – Human-readable name.
* `description` – Optional description.
* `source` – How the list was created.
* `double_opt_in` – Whether double opt-in is enabled.
* `member_count` – Number of subscribed members.
* `created_at` / `updated_at` – ISO timestamps.

## Response Example

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "items": [
      {
        "id": "lists_01J0CBFPXW7SP2N8A9Q7T2048Q",
        "workspace_id": "workspaces_01HZYPM2QF2R8X9SZQ0J9SYBCN",
        "name": "Newsletter Subscribers",
        "description": "Main newsletter list",
        "source": "signup_form",
        "double_opt_in": true,
        "member_count": 1523,
        "created_at": "2025-01-08T10:22:31.000Z",
        "updated_at": "2025-02-02T14:12:40.000Z"
      }
    ],
    "meta": {
      "total": 1,
      "limit": 50,
      "offset": 0
    }
  }
  ```
</ResponseExample>