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

# get_lists

> Which Lists this workspace has, and who is on each one.

> [!NOTE]
>
> Read-only. It never sends and never changes a List.

A List is a saved set of people (or accounts) you plan to invite. get\_lists enumerates them, or, with a `list_id`, returns one List and its members a page at a time. Call it whenever you need a `list_id` instead of rebuilding a List from memory.

Follows the [heyBTW MCP rules](https://heybtw.com/docs/mcp/rules.md).

## When to use it

* "What Lists do we have?"
* "Who is on the Q4 target accounts List?"
* "Find the List I saved yesterday so I can invite it to the LA dinner."
* "How many of this List came from an import versus past events?"

## Parameters

| Parameter | Type | Required | Notes |
| - | - | - | - |
| `list_id` | string | No | Omit to enumerate Lists. Give it to read one List and its members. |
| `limit` | integer | No | Default and maximum: 50 Lists, or 100 members per page. Larger values are clamped. |
| `cursor` | string | No | `metadata.pagination.next_cursor` from the previous call of the same shape. Expires after 15 minutes. |
| `contract_version` | string | No | Omit for v1. |

## Response

**Without `list_id`**, `data` holds one row per List, most recently updated first.

| Field | Meaning |
| - | - |
| `list_id`, `name` | The handle to pass to [save\_list](https://heybtw.com/docs/tools/save-list.md) or [activate\_list](https://heybtw.com/docs/tools/activate-list.md). |
| `list_type`, `definition_type`, `status` | For example `audience`, `static` or `dynamic`, `saved` or `draft`. |
| `member_count`, `member_count_basis` | The stored count, or null with `not_evaluated` for a dynamic List. |
| `grain` | `person` or `account`. |
| `purpose` | Null today: no store holds one yet. |
| `target_eligible`, `default_target_universe` | Whether get\_partner\_overlaps can read it as a target list, and whether it belongs to the default Target Universe. |

**With `list_id`**, `data[0]` holds `list` (the same facts), `members`, and the counts below.

| Field | Meaning |
| - | - |
| `members[]` | email, name, title, company\_name, company\_domain, contact\_count (account rows), provenance. |
| `members[].provenance` | `registrant` (attended an event in this workspace), `imported` (via import\_people) or `neither`. |
| `member_total` | The Lists service's own count. |
| `erased_excluded_count` | People erased from the workspace and withheld from the page. |
| `unknown_company_people_count` | On an account List, people with no resolvable company. |
| `degraded`, `criteria_invalid`, `stale` | When a dynamic List could not be fully evaluated. `degraded` true makes the status `partial`. |

This sample is trimmed from a real call today with `list_id` and `limit: 1`.

```json theme={null}
{
  "tool": "get_lists",
  "data": [
    {
      "list": {
        "list_id": "cmvvqo96r000108l5vere46kp",
        "name": "ScaleUp.ai Q4 target accounts",
        "list_type": "audience",
        "definition_type": "static",
        "status": "saved",
        "member_count": 14,
        "member_count_basis": "stored",
        "grain": "person",
        "purpose": null,
        "target_eligible": false,
        "default_target_universe": false
      },
      "members": [
        {
          "email": "hugo.lombardi@saltmarsh.io",
          "name": "Hugo Lombardi",
          "title": "Chief Revenue Officer",
          "company_name": "Saltmarsh Analytics",
          "company_domain": null,
          "contact_count": null,
          "provenance": "registrant"
        }
      ],
      "member_total": 14,
      "erased_excluded_count": 0,
      "degraded": false,
      "criteria_invalid": false,
      "unknown_company_people_count": 0,
      "stale": false
    }
  ],
  "metadata": {
    "pagination": { "limit": 1, "returned": 1, "has_more": true, "next_cursor": "v1.eyJ..." }
  },
  "status": "ok",
  "gaps": []
}
```

## Rules the agent must follow

* List membership is not attendance or sign-up. A row records that someone was saved or imported.
* To invite a List, pass its `list_id` to activate\_list unchanged and follow its preview and confirmation steps.
* Never rebuild a List from earlier save\_list results or session memory. Call this tool.
* Page while `has_more` is true. De-duplicate on `list_id` or email, since a List edited while you page can repeat or skip a row.
* The Global Prospect List is a separate store of target accounts and is not listed here.

## Errors and gaps

* `internal_error`: retry once.
* `entity_not_found`: no List with that `list_id`.
* `invalid_parameter`: a malformed `list_id`, `limit` or `cursor`, or a cursor from another call.
* `query_timeout`: a dynamic List could not be evaluated in time.
* `upstream_crm_error`: the CRM did not answer for a List whose criteria need it.

## Related

* [save\_list](https://heybtw.com/docs/tools/save-list.md): create a List or add people to one.
* [activate\_list](https://heybtw.com/docs/tools/activate-list.md): invite a List, or record invites you sent.
* [get\_partner\_overlaps](https://heybtw.com/docs/tools/get-partner-overlaps.md): reads an account List as a target list.
* Playbook: [Fill the room in the two weeks before](https://heybtw.com/docs/playbooks/invite-sprint.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.