get_lists

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.

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 or activate_list.
`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.

{
  "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.

save_list: create a List or add people to one.
activate_list: invite a List, or record invites you sent.
get_partner_overlaps: reads an account List as a target list.
Playbook: Fill the room in the two weeks before.

Get started

How heyBTW MCP works

Playbooks

Tools: orientation

Tools: events and rosters

Tools: people and invites

Tools: after the event

Tools: accounts and partners

Tools: pipeline

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

​When to use it

​Parameters

​Response

​Rules the agent must follow

​Errors and gaps

​Related

When to use it

Parameters

Response

Rules the agent must follow

Errors and gaps

Related