Tag Archives: performance_max

Performance Max: Create Search Themes beta with the Google Ads API

What’s New

The recently announced search themes beta feature for Performance Max campaigns lets you provide Google AI with valuable inputs about your customers and business to further optimize Performance Max campaign serving and placement. Beginning in Google Ads API v15, you can create search themes for Performance Max campaigns with the API.

How It Works

  • Search themes beta lets you indicate queries that you know your customers are looking for. They are optional and are additive to what queries Performance Max would match by using your URLs, assets, and more.
  • You can add up to 25 search themes per asset group.
  • Search themes will respect brand exclusions in Performance Max and account-level negative keywords. You can configure brand exclusions through campaign criteria using the BRAND criterion type. Similarly, account-level negative keywords are configured at a customer level using CustomerNegativeCriterionService and the NegativeKeywordList criteria.
  • Results driven from search themes will bring your customers to the landing pages you’ve indicated with your Final URL expansion, page feeds, or URL settings. Final URL expansions can be enabled or disabled with url_expansion_opt_out.
  • Search themes will have the same prioritization as your phrase match and broad match keywords in your Search campaigns.
  • You’ll be able to see the search categories that your ads matched to, and associated conversion performance, in your search terms insights at both the campaign and account levels with the campaign_search_term_insight and customer_search_term_insight reports. You can also view search term insights for custom date ranges, download your data, and access it using the API.

Implementation Details

In the Google Ads API, a search theme is a type of AssetGroupSignal, which can be attached to Performance Max campaigns at the asset group level. You can add a search theme to an asset group by creating an AssetGroupSignal and populating the

AssetGroupSignal.search_theme with a SearchThemeInfo criterion containing a text string representing your search theme, for example, "activities for children". In addition, you must populate the AssetGroupSignal.asset_group with the resource name of an existing asset group you are targeting.

Here is a Java example for creating a search theme asset group signal:

// Creates a search theme asset group signal.
AssetGroupSignal assetGroupSignal =
            SearchThemeInfo.newBuilder().setText("activities for children").build())

You can add multiple asset group signals to a single asset group by creating multiple AssetGroupSignal objects targeting the same asset group. However, each AssetGroupSignal object can only represent a single search theme or audience signal.


You can use the asset_group_signal resource to get the search themes present in a Google Ads account. While performance metrics are currently available at the asset group level, they are not available at the asset group signal level.

Here is a GAQL example to retrieve search theme texts for a specific asset group:

FROM asset_group_signal
  asset_group.id = <Asset Group ID>

Policy Exemptions

In v15 of the Google Ads API, we also introduced two new fields to provide additional information about search_theme approval: asset_group_signal.approval_status and asset_group_signal.disapproval_reasons. Search theme text must be approved by Google. The asset_group_signal.approval_status field provides information about the approval status, and if the search theme text is not approved, the asset_group_signal.disapproval_reasons field lists the reasons why.

Here is a GAQL example to retrieve search theme texts with policy review information for a specific asset group:

FROM asset_group_signal 
  asset_group.id = <Asset Group ID>

If your search theme text is not approved, and you believe the usage adheres to Google’s policies, you can submit a policy exemption request for the search theme that triggered the policy violation.

For example, if your search theme contains medical terms, and you believe the usage of the terms adheres to Google Ads policies and warrants further review, you can use the AssetGroupSignalOperation.exempt_policy_violation_keys[] field to request a policy exemption.

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

If you are new to Performance Max Campaigns, you can learn more with our getting started guide. Check out our asset groups and asset group signals guides to learn more.

Performance Max: create listing groups using batch processing

What’s New

Starting on October 4, 2023, AssetGroupListingGroupFilters can be created asynchronously using batch processing with the Google Ads API. If you use BatchJobService to create AssetGroupListingGroupFilter entities and other Performance Max resources in a single request, errors in the listing group tree creation will not block the creation of the remaining entities. However, the operations to create a listing group tree will still be atomic. This means that if any operation related to the creation of a listing group tree returns an error, all operations related to that listing group tree will also fail, save a few caveats, which are detailed in this Jobs & listing group filters guide.

This update does not change the behavior of any existing batch jobs that do not include operations that create listing group filters.

Previous Behavior

Prior to October 4, 2023, AssetGroupListingGroupFilters could only be created synchronously using the GoogleAdsService.Mutate or AssetGroupListingGroupFilterService.MutateAssetGroupListingGroupFilters method. Requests using the GoogleAdsService.Mutate method are always atomic when they contain AssetGroupListingGroupFilterOperation operations. This is because partial_failure is not supported for these operations, which means that an error in listing group tree creation would block all other operations in the request. If you tried creating AssetGroupListingGroupFilter entities prior to October 4, 2023 using batch processing, you would receive a MutateError.OPERATION_DOES_NOT_SUPPORT_PARTIAL_FAILURE error.

Change Rationale

Batch processing is a powerful feature in the Google Ads API that allows you to dispatch a set of operations, which may be interdependent, to multiple services without synchronously waiting for the operations to complete. We have made batch processing available for AssetGroupListingGroupFilters in response to your feedback to provide another option for creating listing group trees asynchronously and without blocking other operations in the same request.

Implementation Details

In order to add an AssetGroupListingGroupFilter using a batch job:

  1. Create a MutateOperation containing an AssetGroupListingGroupFilterOperation. This is no different than creating a MutateOperation using the GoogleAdsService.Mutate service.
  2. Add the MutateOperation to the batch job as you would with any other type of operation.

The example below demonstrates the process of adding a single AssetGroupListingGroupFilter to an existing batch job. See the Creating Shopping Listing Groups guide to learn more about creating product partition trees using AssetGroupListingGroupFilter entities.

// Constructs the AssetGroupListingGroupFilter.
AssetGroupListingGroupFilter listingGroupFilter =

// Constructs the operation to create the AssetGroupListingGroupFilter.
MutateOperation operation = MutateOperation.newBuilder()

// Sends a request to add the operation to the batch job.
AddBatchJobOperationsResponse response =

The following resources contain additional information to help you with your integration:

Improving Performance Max integrations Blog Series

This article is part of a series that discusses new and upcoming features that you have been asking for. We’ll cover what’s new and how it differs from the current implementation approach.

Keep an eye out for further updates and improvements on our developer blog, continue providing feedback on Performance Max integrations with the Google Ads API, and as always, contact our team if you need support.

Announcing New Reporting Script for Performance Max

Today, we’re announcing the publishing of a new pre-written Script for reporting on Performance Max campaign performance in Google Ads scripts. This script will report on your conversions and other performance related metrics for your campaigns. The only thing needed to get it running is to copy the source code into your account and schedule the script to run daily.

How can I get started?
Find the script here.

If you have any questions or need additional help, contact us via the forum.

Performance Max success story driven by Google Ads API with Kueez

Today, we’re proud to share Kueez’s success story of using the Google Ads API with Performance Max to grow ROAS for partners by 20%!

Here are the highlights:
  • Kueez leverages Google Ads to drive platform ad views from high-quality and engaged traffic across their portfolio of publisher partners, and owned and operated websites.
  • Using the power of Google Ads API, Kueez implemented Performance Max campaigns to broaden their reach, and attract additional audiences that exhibit similar or better conversion rates than they had before using Performance Max.
  • Within 45 days of activating Performance Max campaigns, Kueez achieved an increase of over 50% engaged visits at a similar CPA, and drove +20% ROAS.
Where can I learn more?
We're constantly looking to improve the Google Ads API developer experience. If you have feedback on using Performance Max in the Google Ads API, submit it through this form.

If you have any questions or need additional help, contact us via the forum.