Google Ads

Labels  |  AdWords API  |  Google Developers

Labels allow you to categorize your campaigns, ad groups, ads,
and keywords, and use those categories to simplify your workflow in a variety
of ways.

This guide covers the steps required to do the following:

  • Create labels.
  • Assign labels to your campaigns.
  • Retrieve and filter report results by label, using CampaignService
    get() and
    query() requests.

This guide focuses on campaigns, but you can use the same approach
for ad groups, ads, and keywords.

Use cases

Typical scenarios for using labels include the following:

  • Your account has campaigns you enable only during certain times of the
    year, and you want to easily include
    or exclude those campaigns from reports.
  • You added a new set of keywords to your ad group and you want to
    compare their stats to other keywords in your ad group.
  • Users of your Google Ads account each manage a subset of campaigns and you
    want an easy way to identify the set of campaigns for each user.
  • Your application needs to mark the status of certain objects as processed, audited,
    highlighted, etc.

See the Help Center article on using
for additional
information and an example of how labels work in Google Ads.

Create labels

You create labels using a
TextLabel object.
To create a TextLabel:

  1. Create a TextLabel object.
  2. Set its name.
  3. Wrap the TextLabel in a LabelOperation and send it to

You’ll need the IDs of the new labels for the next steps, so make sure
you capture them from the mutate call’s response, or use
LabelService.get() or
LabelService.query() to
retrieve the IDs.

Assign labels to your campaigns, ad groups, criteria, or ads

Use the mutateLabels operation to assign labels. For example, to assign
labels to a campaign, use
with one or more
objects, each of which consists of the following:

  • labelId – The ID of a label
  • campaignId – The ID of a campaign

Create a CampaignLabel object for each label/campaign pair you want to add,
wrap it in a CampaignLabelOperation with the ADD operator, and send it to

Retrieve objects using their labels

Now that you’ve assigned labels to your campaigns, you can use the Labels
field to retrieve objects that have one or more specific labels. For example,
here’s a
AWQL statement that will select the ID, name, and labels for each campaign
associated with any one of three label IDs.

SELECT Id, Name, Labels
WHERE Labels CONTAINS_ANY [123456, 789012, 345678]

A few tips to keep in mind when defining filters with labels:

  1. Make sure you filter by label ID, not label name.
  2. The only supported operators are: CONTAINS_ALL, CONTAINS_ANY, and

Use the Labels field in reports

Each of the following reports has Labels and LabelIds fields:

As with other fields of type List, you can filter reporting results by

The reporting service returns a semicolon-separated list of label
names and IDs in the Labels and LabelIds fields, for example:

Campaign ID,Labels,Label IDs
1999999,Label 1; Label 2,456; 678
2999999,Label 2;678
Total, --, --

Code examples

The Campaign Management folder of each client
contains code examples
for adding labels to campaigns and retrieving campaigns by label:

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button