Stay organized with collectionsSave and categorize content based on your preferences.
You can combine two or more existing user lists to create even more
sophisticated targeting.
Create the user list
You can construct custom combinations of existing user lists as alogical_user_listwithUserListLogicalRuleInfofields. The
rules in thelogical_user_listareANDed, so a user must match every rule to
be considered in the list. However, each rule lets you specify whether its
operands areANDed orORed. In other words, you can specify whether the user
must fulfillallof the rule operands or just one of them.
In addition, rules let you specify otherlogical_user_listobjects as
operands, effectively letting you create a tree of them.logical_user_listcan
be a very powerful way of defining complex hierarchies of groups for your
targeting. You can combine lists with differentAccessReasonfields. However,
if access is revoked, then thatUserListwill be treated as a list with no
members when the rules of thelogical_user_listare evaluated.
The following code shows how to create alogical_user_listcontaining users in
either of twobasic_user_listinstances:
defmain(client:GoogleAdsClient,customer_id:str,user_list_ids:List[str])->None:"""Creates a combination user list.Args:client: The Google Ads client.customer_id: The customer ID for which to add the user list.user_list_ids: A list of user list IDs to logically combine."""# Get the UserListService client.user_list_service:UserListServiceClient=client.get_service("UserListService")# Add each of the provided list IDs to a list of rule operands specifying# which lists the operator should target.logical_user_list_operand_info_list:List[LogicalUserListOperandInfo]=[]foruser_list_idinuser_list_ids:logical_user_list_operand_info:LogicalUserListOperandInfo=(client.get_type("LogicalUserListOperandInfo"))logical_user_list_operand_info.user_list=(user_list_service.user_list_path(customer_id,user_list_id))logical_user_list_operand_info_list.append(logical_user_list_operand_info)# Create a UserListOperation and populate the UserList.user_list_operation:UserListOperation=client.get_type("UserListOperation")user_list:UserList=user_list_operation.createuser_list.name=f"My combination list of other user lists #{uuid4()}"# Create a UserListLogicalRuleInfo specifying that a user should be added to# the new list if they are present in any of the provided lists.user_list_logical_rule_info:UserListLogicalRuleInfo=client.get_type("UserListLogicalRuleInfo")# Using ANY means that a user should be added to the combined list if they# are present on any of the lists targeted in the# LogicalUserListOperandInfo. Use ALL to add users present on all of the# provided lists or NONE to add users that aren't present on any of the# targeted lists.user_list_logical_rule_info.operator=(client.enums.UserListLogicalRuleOperatorEnum.ANY)user_list_logical_rule_info.rule_operands.extend(logical_user_list_operand_info_list)user_list.logical_user_list.rules.append(user_list_logical_rule_info)# Issue a mutate request to add the user list, then print the results.response:MutateUserListsResponse=user_list_service.mutate_user_lists(customer_id=customer_id,operations=[user_list_operation])print("Created logical user list with resource name "f"'{response.results[0].resource_name}.'")
defadd_logical_user_list(customer_id,user_list_ids)# GoogleAdsClient will read a config file from# ENV['HOME']/google_ads_config.rb when called without parametersclient=Google::Ads::GoogleAds::GoogleAdsClient.new# Creates the UserListLogicalRuleInfo specifying that a user should be added# to the new list if they are present in any of the provided lists.user_list_logical_rule_info=client.resource.user_list_logical_rule_infodo|info|# Using ANY means that a user should be added to the combined list if they# are present on any of the lists targeted in the logical_user_list_operand_info.# Use ALL to add users present on all of the provided lists or NONE to add# users that aren't present on any of the targeted lists.info.operator=:ANYuser_list_ids.eachdo|list_id|info.rule_operands<<client.resource.logical_user_list_operand_infodo|op|op.user_list=client.path.user_list(customer_id,list_id)endendend# Creates the new combination user list operation.operation=client.operation.create_resource.user_listdo|ul|ul.name="My combination list of other user lists#{(Time.new.to_f*1000).to_i}"ul.logical_user_list=client.resource.logical_user_list_infodo|info|info.rules<<user_list_logical_rule_infoendend# Issues a mutate request to add the user list and prints some information.response=client.service.user_list.mutate_user_lists(customer_id:customer_id,operations:[operation],)puts"Created combination user list with resource name "\"'#{response.results.first.resource_name}'"end
subadd_logical_user_list{my($api_client,$customer_id,$user_list_ids)=@_;# Add each of the provided list IDs to a list of rule operands specifying which# lists the operator should target.my$logical_user_list_operand_info_list=[];foreachmy$user_list_id(@$user_list_ids){push@$logical_user_list_operand_info_list,Google::Ads::GoogleAds::V21::Common::LogicalUserListOperandInfo->new({userList=>Google::Ads::GoogleAds::V21::Utils::ResourceNames::user_list($customer_id,$user_list_id)});}# Create the UserListLogicalRuleInfo specifying that a user should be added to# the new list if they are present in any of the provided lists.my$user_list_logical_rule_info=Google::Ads::GoogleAds::V21::Common::UserListLogicalRuleInfo->new({# Using ANY means that a user should be added to the combined list if they# are present on any of the lists targeted in the LogicalUserListOperandInfo.# Use ALL to add users present on all of the provided lists or NONE to add# users that aren't present on any of the targeted lists.operator=>ANY,ruleOperands=>$logical_user_list_operand_info_list});# Create the new combination user list.my$user_list=Google::Ads::GoogleAds::V21::Resources::UserList->new({name=>"My combination list of other user lists #".uniqid(),logicalUserList=>Google::Ads::GoogleAds::V21::Common::LogicalUserListInfo->new({rules=>[$user_list_logical_rule_info]})});# Create the operation.my$user_list_operation=Google::Ads::GoogleAds::V21::Services::UserListService::UserListOperation->new({create=>$user_list});# Issue a mutate request to add the user list and print some information.my$user_lists_response=$api_client->UserListService()->mutate({customerId=>$customer_id,operations=>[$user_list_operation]});printf"Created combination user list with resource name '%s'.\n",$user_lists_response->{results}[0]{resourceName};return1;}
With your audience segment created, the next step is to target it.
Audience segment targeting rules
Positive (biddable) user lists cannot be set at the campaign level and the
ad group level at the same time. Positive user list criteria must be removed
from all ad groups within a campaign before one can be set for the campaign.
Positive targeting by user list is only supported for Search campaigns. For
Display campaigns,CampaignCriterionthat setsuser_listmust be
excluded.
In Search and Shopping campaigns, user list targets don't support setting
the following fields:
The process is similar to other types of targeting criteria in the API. The
following code demonstrates how you can use anAdGroupCriterionto target ads in an ad group to a user list:
deftarget_ads_in_ad_group_to_user_list(client:GoogleAdsClient,customer_id:str,ad_group_id:str,user_list_resource_name:str,)->str:"""Creates an ad group criterion that targets a user list with an ad group.Args:client: an initialized GoogleAdsClient instance.customer_id: a str client customer ID used to create an ad groupcriterion.ad_group_id: a str ID for an ad group used to create an ad groupcriterion that targets members of a user list.user_list_resource_name: a str resource name for a user list.Returns:a str resource name for an ad group criterion."""ad_group_criterion_operation:AdGroupCriterionOperation=client.get_type("AdGroupCriterionOperation")# Creates the ad group criterion targeting members of the user list.ad_group_criterion:AdGroupCriterion=ad_group_criterion_operation.createad_group_criterion.ad_group=client.get_service("AdGroupService").ad_group_path(customer_id,ad_group_id)ad_group_criterion.user_list.user_list=user_list_resource_namead_group_criterion_service:AdGroupCriterionServiceClient=(client.get_service("AdGroupCriterionService"))response:MutateAdGroupCriteriaResponse=(ad_group_criterion_service.mutate_ad_group_criteria(customer_id=customer_id,operations=[ad_group_criterion_operation]))resource_name:str=response.results[0].resource_nameprint("Successfully created ad group criterion with resource name: "f"'{resource_name}' targeting user list with resource name: "f"'{user_list_resource_name}' and with ad group with ID "f"{ad_group_id}.")returnresource_name
deftarget_ads_in_ad_group_to_user_list(client,customer_id,ad_group_id,user_list)# Creates the ad group criterion targeting members of the user list.operation=client.operation.create_resource.ad_group_criteriondo|agc|agc.ad_group=client.path.ad_group(customer_id,ad_group_id)agc.user_list=client.resource.user_list_infodo|info|info.user_list=user_listendend# Issues a mutate request to create the ad group criterion.response=client.service.ad_group_criterion.mutate_ad_group_criteria(customer_id:customer_id,operations:[operation],)ad_group_criterion_resource_name=response.results.first.resource_nameputs"Successfully created ad group criterion with resource name "\"'#{ad_group_criterion_resource_name}' targeting user list with resource name "\"'#{user_list}' with ad group with ID#{ad_group_id}"ad_group_criterion_resource_nameend
subtarget_ads_in_ad_group_to_user_list{my($api_client,$customer_id,$ad_group_id,$user_list_resource_name)=@_;# Create the ad group criterion targeting members of the user list.my$ad_group_criterion=Google::Ads::GoogleAds::V21::Resources::AdGroupCriterion->new({adGroup=>Google::Ads::GoogleAds::V21::Utils::ResourceNames::ad_group($customer_id,$ad_group_id),userList=>Google::Ads::GoogleAds::V21::Common::UserListInfo->new({userList=>$user_list_resource_name})});# Create the operation.my$ad_group_criterion_operation=Google::Ads::GoogleAds::V21::Services::AdGroupCriterionService::AdGroupCriterionOperation->new({create=>$ad_group_criterion});# Add the ad group criterion, then print and return the new criterion's resource name.my$ad_group_criteria_response=$api_client->AdGroupCriterionService()->mutate({customerId=>$customer_id,operations=>[$ad_group_criterion_operation]});my$ad_group_criterion_resource_name=$ad_group_criteria_response->{results}[0]{resourceName};printf"Successfully created ad group criterion with resource name '%s' "."targeting user list with resource name '%s' with ad group with ID %d.\n",$ad_group_criterion_resource_name,$user_list_resource_name,$ad_group_id;return$ad_group_criterion_resource_name;}
As with other types of criteria, you can assign other properties to theAdGroupCriterionobject, such as bid overrides.
Switch targeting levels
If you are switching from ad group level user list criteria to campaign level,
you must first remove the existing user list criteria from each enabled or
paused ad group under that campaign. Click the expandable elements to view
example code for each step.
First, retrieve all of the AdGroupCriteria under a given campaign.
defget_user_list_ad_group_criteria(client:GoogleAdsClient,customer_id:str,campaign_id:str)->List[str]:"""Finds all of user list ad group criteria under a campaign.Args:client: an initialized GoogleAdsClient instance.customer_id: a str client customer ID.campaign_id: a str campaign ID.Returns:a list of ad group criterion resource names."""# Creates a query that retrieves all of the ad group criteria under a# campaign.query:str=f"""SELECTad_group_criterion.criterion_idFROM ad_group_criterionWHERE campaign.id ={campaign_id}AND ad_group_criterion.type = USER_LIST"""googleads_service:GoogleAdsServiceClient=client.get_service("GoogleAdsService")search_request:SearchGoogleAdsRequest=client.get_type("SearchGoogleAdsRequest")search_request.customer_id=customer_idsearch_request.query=queryresponse:SearchGoogleAdsResponse=googleads_service.search(request=search_request)# Iterates over all rows in all pages. Prints the user list criteria and# adds the ad group criteria resource names to the list.user_list_criteria:List[str]=[]row:GoogleAdsRowforrowinresponse:resource_name:str=row.ad_group_criterion.resource_nameprint("Ad group criterion with resource name '{resource_name}' was ""found.")user_list_criteria.append(resource_name)returnuser_list_criteria
defget_user_list_ad_group_criterion(client,customer_id,campaign_id)user_list_criteria=[]# Creates a query that will retrieve all of the ad group criteria# under a campaign.query=<<~QUERYSELECTad_group_criterion.criterion_idFROMad_group_criterionWHEREcampaign.id=#{campaign_id}ANDad_group_criterion.type='USER_LIST'QUERY# Issues the search request.response=client.service.google_ads.search(customer_id:customer_id,query:query,)# Iterates over all rows in all pages. Prints the results and adds the ad# group criteria resource names to the list.response.eachdo|row|ad_group_criterion_resource_name=row.ad_group_criterion.resource_nameputs"Ad group criterion with resource name "\"'#{ad_group_criterion_resource_name}' was found"user_list_criteria<<ad_group_criterion_resource_nameenduser_list_criteriaend
subget_user_list_ad_group_criteria{my($api_client,$customer_id,$campaign_id)=@_;my$user_list_criterion_resource_names=[];# Create a search stream request that will retrieve all of the user list ad# group criteria under a campaign.my$search_stream_request=Google::Ads::GoogleAds::V21::Services::GoogleAdsService::SearchGoogleAdsStreamRequest->new({customerId=>$customer_id,query=>sprintf("SELECT ad_group_criterion.criterion_id "."FROM ad_group_criterion "."WHERE campaign.id = %d AND ad_group_criterion.type = 'USER_LIST'",$campaign_id)});my$search_stream_handler=Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({service=>$api_client->GoogleAdsService(),request=>$search_stream_request});# Issue a search request and process the stream response.$search_stream_handler->process_contents(sub{# Display the results and add the resource names to the list.my$google_ads_row=shift;my$ad_group_criterion_resource_name=$google_ads_row->{adGroupCriterion}{resourceName};printf"Ad group criterion with resource name '%s' was found.\n",$ad_group_criterion_resource_name;push(@$user_list_criterion_resource_names,$ad_group_criterion_resource_name);});return$user_list_criterion_resource_names;}
defremove_existing_criteria_from_ad_group(client:GoogleAdsClient,customer_id:str,campaign_id:str)->None:"""Removes all ad group criteria targeting a user list under a campaign.This is a necessary step before targeting a user list at the campaign level.Args:client: an initialized GoogleAdsClient instance.customer_id: a str client customer ID.campaign_id: a str ID for a campaign that will have all ad groupcriteria that targets user lists removed."""# Retrieves all of the ad group criteria under a campaign.all_ad_group_criteria:List[str]=get_user_list_ad_group_criteria(client,customer_id,campaign_id)# Creates a list of remove operations.remove_operations:List[AdGroupCriterionOperation]=[]forad_group_criterion_resource_nameinall_ad_group_criteria:remove_operation:AdGroupCriterionOperation=client.get_type("AdGroupCriterionOperation")remove_operation.remove=ad_group_criterion_resource_nameremove_operations.append(remove_operation)ad_group_criterion_service:AdGroupCriterionServiceClient=(client.get_service("AdGroupCriterionService"))response:MutateAdGroupCriteriaResponse=(ad_group_criterion_service.mutate_ad_group_criteria(customer_id=customer_id,operations=remove_operations))print("Successfully removed ad group criterion with resource name: "f"'{response.results[0].resource_name}'")
defremove_existing_list_criteria_from_ad_group(client,customer_id,campaign_id)# Retrieves all of the ad group criteria under a campaign.ad_group_criteria=get_user_list_ad_group_criterion(client,customer_id,campaign_id)# Creates a list of remove operations.operations=[]ad_group_criteria.eachdo|agc|operations<<client.operation.remove_resource.ad_group_criterion(agc)end# Issues a mutate request to remove all ad group criteria.response=client.service.ad_group_criterion.mutate_ad_group_criteria(customer_id:customer_id,operations:operations,)puts"Removed#{response.results.size}ad group criteria."response.results.eachdo|result|puts"Successfully removed ad group criterion with resource name "\"'#{result.resource_name}'"endend
subremove_existing_list_criteria_from_ad_group{my($api_client,$customer_id,$campaign_id)=@_;# Retrieve all of the ad group criteria under a campaign.my$ad_group_criteria=get_user_list_ad_group_criteria($api_client,$customer_id,$campaign_id);# Create a list of remove operations.my$operations=[];foreachmy$ad_group_criterion(@$ad_group_criteria){push(@$operations,Google::Ads::GoogleAds::V21::Services::AdGroupCriterionService::AdGroupCriterionOperation->new({remove=>$ad_group_criterion}));}# Remove the ad group criteria and print the resource names of the removed criteria.my$ad_group_criteria_response=$api_client->AdGroupCriterionService()->mutate({customerId=>$customer_id,operations=>$operations});printf"Removed %d ad group criteria.\n",scalar@{$ad_group_criteria_response->{results}};foreachmy$result(@{$ad_group_criteria_response->{results}}){printf"Successfully removed ad group criterion with resource name '%s'.\n",$result->{resourceName};}}
Existing campaign level user list criteria must also be removed when switching
to ad group level user lists, and the process mirrors the preceding example.
Target ads in a campaign to a user list, using a CampaignCriterion.
deftarget_ads_in_campaign_to_user_list(client:GoogleAdsClient,customer_id:str,campaign_id:str,user_list_resource_name:str,)->str:"""Creates a campaign criterion that targets a user list with a campaign.Args:client: an initialized GoogleAdsClient instance.customer_id: a str client customer ID used to create an campaigncriterion.campaign_id: a str ID for a campaign used to create a campaigncriterion that targets members of a user list.user_list_resource_name: a str resource name for a user list.Returns:a str resource name for a campaign criterion."""campaign_criterion_operation:CampaignCriterionOperation=client.get_type("CampaignCriterionOperation")campaign_criterion:CampaignCriterion=campaign_criterion_operation.createcampaign_criterion.campaign=client.get_service("CampaignService").campaign_path(customer_id,campaign_id)campaign_criterion.user_list.user_list=user_list_resource_namecampaign_criterion_service:CampaignCriterionServiceClient=(client.get_service("CampaignCriterionService"))response:MutateCampaignCriteriaResponse=(campaign_criterion_service.mutate_campaign_criteria(customer_id=customer_id,operations=[campaign_criterion_operation]))resource_name:str=response.results[0].resource_nameprint("Successfully created campaign criterion with resource name "f"'{resource_name}' targeting user list with resource name "f"'{user_list_resource_name}' with campaign with ID{campaign_id}")returnresource_name
deftarget_ads_in_campaign_to_user_list(client,customer_id,campaign_id,user_list)# Creates the campaign criterion targeting members of the user list.operation=client.operation.create_resource.campaign_criteriondo|cc|cc.campaign=client.path.campaign(customer_id,campaign_id)cc.user_list=client.resource.user_list_infodo|info|info.user_list=user_listendend# Issues a mutate request to create the campaign criterion.response=client.service.campaign_criterion.mutate_campaign_criteria(customer_id:customer_id,operations:[operation],)campaign_criterion_resource_name=response.results.first.resource_nameputs"Successfully created campaign criterion with resource name "\"'#{campaign_criterion_resource_name}' targeting user list with resource name "\"'#{user_list}' with campaign with ID#{campaign_id}"campaign_criterion_resource_nameend
subtarget_ads_in_campaign_to_user_list{my($api_client,$customer_id,$campaign_id,$user_list_resource_name)=@_;# Create the campaign criterion.my$campaign_criterion=Google::Ads::GoogleAds::V21::Resources::CampaignCriterion->new({campaign=>Google::Ads::GoogleAds::V21::Utils::ResourceNames::campaign($customer_id,$campaign_id),userList=>Google::Ads::GoogleAds::V21::Common::UserListInfo->new({userList=>$user_list_resource_name})});# Create the operation.my$campaign_criterion_operation=Google::Ads::GoogleAds::V21::Services::CampaignCriterionService::CampaignCriterionOperation->new({create=>$campaign_criterion});# Add the campaign criterion and print the resulting criterion's resource name.my$campaign_criteria_response=$api_client->CampaignCriterionService()->mutate({customerId=>$customer_id,operations=>[$campaign_criterion_operation]});my$campaign_criterion_resource_name=$campaign_criteria_response->{results}[0]{resourceName};printf"Successfully created campaign criterion with resource name '%s' "."targeting user list with resource name '%s' with campaign with ID %d.\n",$campaign_criterion_resource_name,$user_list_resource_name,$campaign_id;return$campaign_criterion_resource_name;}
In order to collect performance data for your audience segments, issue a search
request against thead_group_audience_viewor thecampaign_audience_viewresource.
For example, you might look at theconversionsorcost_per_conversionto
determine if targeting the audience segment is actually leading to more
conversions, then adjust your bid modifiers accordingly.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-03 UTC."],[[["\u003cp\u003eLogical user lists empower advanced targeting by combining existing user lists using logical operators like \u003ccode\u003eAND\u003c/code\u003e, \u003ccode\u003eOR\u003c/code\u003e, \u003ccode\u003eANY\u003c/code\u003e, \u003ccode\u003eALL\u003c/code\u003e, and \u003ccode\u003eNONE\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003e\u003ccode\u003elogical_user_list\u003c/code\u003e differs from \u003ccode\u003erule_based_user_list\u003c/code\u003e, which relies on remarketing tag parameters.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Ads Query Language allows retrieval of user list details, including name, membership, and lifespan.\u003c/p\u003e\n"],["\u003cp\u003eSearch campaigns can use positive user list targeting directly, while Display campaigns require exclusion through \u003ccode\u003eCampaignCriterion\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eAd group targeting is achieved using \u003ccode\u003eAdGroupCriterion\u003c/code\u003e, which links an ad group to a user list and supports exclusion by setting \u003ccode\u003enegative\u003c/code\u003e to \u003ccode\u003etrue\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,[]]