list_lead_lists
Read-only
Retrieve and organize lead lists from Instantly.ai with pagination support. Filter lists by auto-enrichment status or search by name to manage lead containers outside of campaigns.
Instructions
List lead lists with cursor-based pagination (100 per page).
PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after= to get next page. Continue until pagination.next_starting_after is null.
Lead lists are containers for organizing leads outside of campaigns. Use has_enrichment_task filter to find lists with auto-enrichment enabled.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/instantly_mcp/tools/leads.py:204-244 (handler)The main handler function implementing the list_lead_lists tool. Calls the Instantly API /lead-lists endpoint with pagination and filtering parameters, adds LLM-friendly pagination hints, and returns JSON.
async def list_lead_lists(params: Optional[ListLeadListsInput] = None) -> str: """ List lead lists with cursor-based pagination (100 per page). PAGINATION: If response contains pagination.next_starting_after, there are MORE results. Call again with starting_after=<that value> to get next page. Continue until pagination.next_starting_after is null. Lead lists are containers for organizing leads outside of campaigns. Use has_enrichment_task filter to find lists with auto-enrichment enabled. """ client = get_client() # Handle case where params is None (for OpenAI/non-Claude clients) # Set default limit=100 to return more results by default if params is None: params = ListLeadListsInput(limit=100) query_params = {} if params.limit: query_params["limit"] = params.limit else: # Default to 100 results if no limit specified query_params["limit"] = 100 if params.starting_after: query_params["starting_after"] = params.starting_after if params.has_enrichment_task is not None: query_params["has_enrichment_task"] = params.has_enrichment_task if params.search: query_params["search"] = params.search result = await client.get("/lead-lists", params=query_params) # Add pagination guidance for LLMs if isinstance(result, dict): pagination = result.get("pagination", {}) next_cursor = pagination.get("next_starting_after") if next_cursor: result["_pagination_hint"] = f"MORE RESULTS AVAILABLE. Call list_lead_lists with starting_after='{next_cursor}' to get next page." return json.dumps(result, indent=2) - Pydantic BaseModel defining the input parameters for the list_lead_lists tool, including pagination, search, and filter options.
class ListLeadListsInput(BaseModel): """Input for listing lead lists with pagination.""" # Use extra="ignore" to be tolerant of unexpected fields from LLMs model_config = ConfigDict(str_strip_whitespace=True, extra="ignore") limit: Optional[int] = Field(default=100, ge=1, le=100, description="Results per page (1-100, default: 100)") starting_after: Optional[str] = Field( default=None, description="Pagination cursor - use value from pagination.next_starting_after to get next page" ) has_enrichment_task: Optional[bool] = Field(default=None) search: Optional[str] = Field(default=None, description="Search by name") - src/instantly_mcp/server.py:91-91 (registration)MCP tool registration annotation in server.py specifying that list_lead_lists is a read-only operation.
"list_lead_lists": {"readOnlyHint": True}, - src/instantly_mcp/tools/leads.py:455-455 (registration)Inclusion of the list_lead_lists handler in the LEAD_TOOLS list for export and registration.
list_lead_lists, - Export of ListLeadListsInput schema model for use across the codebase.
ListLeadListsInput,