google_ads_list_user_lists
List all user lists (audiences) from a Google Ads account. Filter by type like CRM-based or rule-based for targeted audience analysis.
Instructions
List all user lists (audiences) in the account.
Args: customer_id: Customer ID (without hyphens) list_type: Optional filter by type (CRMBASED, RULE_BASED, SIMILAR, LOGICAL)
Returns: List of all user lists with details
Example: google_ads_list_user_lists( customer_id="1234567890", list_type="CRMBASED" )
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customer_id | Yes | ||
| list_type | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- The MCP tool handler function 'google_ads_list_user_lists' - decorated with @mcp.tool(), it takes customer_id and optional list_type, validates the list_type against UserListType enum, calls audience_manager.list_user_lists(), formats the results as a Markdown string with user list details (ID, type, description, sizes, match rate, duration, status), and handles errors.
@mcp.tool() def google_ads_list_user_lists( customer_id: str, list_type: Optional[str] = None ) -> str: """ List all user lists (audiences) in the account. Args: customer_id: Customer ID (without hyphens) list_type: Optional filter by type (CRMBASED, RULE_BASED, SIMILAR, LOGICAL) Returns: List of all user lists with details Example: google_ads_list_user_lists( customer_id="1234567890", list_type="CRMBASED" ) """ with performance_logger.track_operation('list_user_lists', customer_id=customer_id): try: client = get_auth_manager().get_client() audience_manager = AudienceManager(client) # Validate list type if provided ul_type = None if list_type: try: ul_type = UserListType[list_type.upper()] except KeyError: valid_types = [t.value for t in UserListType] return f"❌ Invalid list type. Valid types: {', '.join(valid_types)}" user_lists = audience_manager.list_user_lists(customer_id, ul_type) # Audit log audit_logger.log_api_call( customer_id=customer_id, operation="list_user_lists", resource_type="user_list", action="read", result="success", details={'count': len(user_lists)} ) if not user_lists: return "No user lists found. Create one with `google_ads_create_user_list`." # Format response output = f"# User Lists (Audiences)\n\n" output += f"**Total Lists**: {len(user_lists)}\n\n" for ul in user_lists: output += f"## {ul['name']}\n\n" output += f"- **ID**: {ul['id']}\n" output += f"- **Type**: {ul['type']}\n" if ul['description']: output += f"- **Description**: {ul['description']}\n" output += f"- **Search Network Size**: {ul['size_for_search']:,}\n" output += f"- **Display Network Size**: {ul['size_for_display']:,}\n" if ul['match_rate_percentage']: output += f"- **Match Rate**: {ul['match_rate_percentage']:.1f}%\n" output += f"- **Membership Duration**: {ul['membership_life_span']} days\n" output += f"- **Status**: {ul['membership_status']}\n\n" return output except Exception as e: error_msg = ErrorHandler.handle_error(e, context="list_user_lists") return f"❌ Failed to list user lists: {error_msg}" - managers/audience_manager.py:536-586 (helper)The AudienceManager.list_user_lists() method that executes the Google Ads API query to fetch user lists. It builds a GAQL query selecting user_list fields (id, name, description, type, sizes, match rate, membership life span, status), optionally filtered by list_type, and returns a list of dictionaries.
def list_user_lists( self, customer_id: str, list_type: Optional[UserListType] = None ) -> List[Dict[str, Any]]: """List all user lists (audiences) in the account. Args: customer_id: Customer ID (without hyphens) list_type: Optional filter by list type Returns: List of user lists with details """ ga_service = self.client.get_service("GoogleAdsService") query = """ SELECT user_list.id, user_list.name, user_list.description, user_list.type, user_list.size_for_display, user_list.size_for_search, user_list.match_rate_percentage, user_list.membership_life_span, user_list.membership_status FROM user_list """ if list_type: query += f" WHERE user_list.type = '{list_type.value}'" response = ga_service.search(customer_id=customer_id, query=query) user_lists = [] for row in response: ul = row.user_list user_lists.append({ 'id': str(ul.id), 'name': ul.name, 'description': ul.description, 'type': ul.type.name, 'size_for_display': ul.size_for_display, 'size_for_search': ul.size_for_search, 'match_rate_percentage': ul.match_rate_percentage, 'membership_life_span': ul.membership_life_span, 'membership_status': ul.membership_status.name }) return user_lists - managers/audience_manager.py:29-34 (schema)The UserListType enum defining valid user list types: CRMBASED, RULE_BASED, LOGICAL, SIMILAR. Used for input validation in the handler.
class UserListType(str, Enum): """User list types for remarketing.""" CRMBASED = "CRMBASED" # Customer Match RULE_BASED = "RULE_BASED" # Website/app visitors LOGICAL = "LOGICAL" # Combination of other lists SIMILAR = "SIMILAR" # Lookalike audiences - tools/audiences/mcp_tools_audiences.py:42-47 (registration)The registration function 'register_audience_tools(mcp)' which contains all the @mcp.tool() decorated tool definitions including google_ads_list_user_lists.
def register_audience_tools(mcp): """Register all audience management tools with the MCP server. Args: mcp: FastMCP server instance """