Labels

Labels allow you to organize elements in your account into meaningful groups so you can quickly and easily filter and report on the data that is of most interest to you. Google Ads scripts support labels at the account, campaign, ad group, ad, and keyword levels.

Use cases

Within Google Ads accounts, labels can be used to associate arbitrary data with Google Ads entities. Within manager accounts, labels can be used to group similar child accounts. Labels present a number of interesting use cases:

Process a list of accounts: If you are an agency, you could apply a plumber_accounts label to all the accounts for plumbers, and then a script can push plumber-related keywords (e.g. "emergency shower repair") into all campaigns in those accounts.
Process a list of entities: If you have a set of keywords that you want to enable only during weekends, you could apply a weekend_keywords label to them. A script could then enable all keywords with weekend_keywords on Friday evening, and pause them on Monday morning.
Process entities across multiple runs: If you have a large number of entities that cannot be processed in under 30 minutes, then you can create a processed label in your script and apply it to entities that have already been processed. Schedule the script to run hourly, and then process only entities that don’t have the processed label applied to them. See the link checker solution for an example.
Two-step changes: Instead of having the script execute a bid change across a large number of keywords, you can label the keywords with increase_bid_by_10%, log in to the Google Ads user interface, filter out the keywords matching the label, review them, and if satisfied with the result, change their bids using Bulk edits.
Flexible bidding: A script could use labels to maintain a history of bid changes. For instance when a script increases a keyword bid by 20%, it can stick the account with a label, increased_20%. The next day when the script runs across the label and realizes it had already increased the bid previously, it may increase the bid by only 10%.
Quality score tracking: A script could label important keywords with their quality scores, then periodically check and report on keywords whose quality score no longer matches the label.

Labels at the account level

Google Ads scripts allow you to create labels within manager accounts, as well as apply labels to Google Ads accounts under that manager account. You can create a label as follows:

var labelName = 'High spending accounts';
AdsManagerApp.createAccountLabel(labelName);

You can then apply this label to the accounts of your choice using the applyLabel method, as follows:

var accountIds = ['123-456-7890', '345-6789-2100'];
var labelName = 'High spending accounts';

var accounts = AdsManagerApp.accounts().withIds(accountIds).get();
while (accounts.hasNext()) {
  var account = accounts.next();
  account.applyLabel(labelName);
}

Similarly, you can remove a label from an account using the removeLabel method, as follows:

var accountIds = ['123-456-7890', '345-6789-2100'];
var labelName = 'High spending accounts';

var accounts = AdsManagerApp.accounts().withIds(accountIds).get();
while (accounts.hasNext()) {
  var account = accounts.next();
  account.removeLabel(labelName);
}

The most common use of account labels is to process a group of accounts sharing the same account label. The following code snippet shows how this is done:

var labelName = 'High spending accounts';

var accounts = AdsManagerApp.accounts()
    .withCondition('LabelNames CONTAINS "' + labelName + '"')
    .get();

Refer to our Ads Manager scripts guide to learn more about processing multiple accounts in a single script execution. You can find more code examples here.

Labels within an account

You can create and apply labels to an account's campaigns, ad groups, ads, and keywords. Here's how to apply a label to a campaign:

var campaign = AdsApp.campaigns()
    .withCondition('Name = "My first campaign"').get().next();
campaign.applyLabel('High performing campaign');

Similarly, you can remove a label using the removeLabel method, as follows:

var campaign = AdsApp.campaigns()
    .withCondition('Name = "My first campaign"').get().next();
campaign.removeLabel('High performing campaign');

Labels are most commonly used to process a set of similar entities grouped together by a label. The following code snippet shows how to pause a group of campaigns sharing a common label:

var label = AdsApp.labels()
    .withCondition('Name = "Christmas promotions"')
    .get().next();
var campaignIterator = label.campaigns().get();
while (campaignIterator.hasNext()) {
  var campaign = campaignIterator.next();
  campaign.pause();
}

Reporting

You can use label IDs to filter for entities when running performance reports for Google Ads accounts. The following code snippet shows how to run a campaign performance report for all campaigns that have a Christmas promotions label:

var label = AdsApp.labels()
    .withCondition("Name = 'Christmas promotions'")
    .get().next();
var query = "SELECT CampaignName, Clicks, Impressions, Cost " +
    "FROM CAMPAIGN_PERFORMANCE_REPORT WHERE Labels CONTAINS_ANY " +
    "[" + label.getId() + "] DURING THIS_MONTH"
var rows = AdsApp.report(query).rows();

Keep in mind that you can use only CONTAINS_ALL, CONTAINS_ANY and CONTAINS_NONE operators for filtering by label IDs.

You can explore our Labels for Branded Keywords solution to learn more about labels in Google Ads accounts. You can find more code examples here.