Google Ads API Version 21 Now Available

Google has released version 21 of the Google Ads API, this is a major release with dozens of updates. Updates include AI Max for Search campaigns, PMax changes, reporting updates and much more. Google also made documentation updates to its Google Ads API help docs.

Before this release was version 20 on June 5, 2025, 19.1 in April 2025, then 19 in February 2025, then version 18 in October 2024. Before that was 17.1 in August 2024 and then before that was version 17.0 in June 2024 and then before that was version 16.1 and then Version 16 in February 2024. Before that was version 15 back in October 2023. Then before that was version 14.1 which was released in August. Version 13.1 preceded this new version, which was released in April 2023. Version 12.0 was released in October 2022, Version 11.0 of the Google Ads API was released in June, and version 11.1 was in August. Also Version 10.1 was released on April 27, 2022 and version 10.0 was released on February 9, 2022. And Google has sunset the AdWords API on April 27th which will completely stop working at the end of July.

Here is a video summary of these changes:

Here is the full change log:

AI Max for Search campaigns:

• You can now use the ai_max_setting.enable_ai_max field of the Campaign to enable AI Max for Search campaigns. AI Max for Search campaigns expands a Search campaign's reach through search term matching and allows controlling whether targeting and creative controls serve when set. Text asset automation and brand list controls that were set in previous version requests will still be respected until AI Max for Search campaigns is explicitly toggled and turned off. Campaign.ai_max_setting.bundling_required can be used to determine if AI Max for Search campaigns must be enabled to respect or modify text asset automation and brand list controls. AdGroup.ai_max_ad_group_setting.disable_search_term_matching can be used to disable search term matching when a parent campaign has enabled AI Max for Search campaigns. See our blog post Unlock next-level performance with AI Max for Search campaigns.
• Added CampaignError.AI_MAX_MUST_BE_ENABLED, which is thrown for Search campaigns when you opt in to FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION without enabling AI Max for Search campaigns on the campaign.
• Added support for applying targeting controls at the ad group level in AI Max for Search campaigns. You can now add the following criteria to ad groups: Brand lists, Locations and Webpages (URL rules)
• Added the ai_max_search_term_ad_combination_view to report on performance for combinations of search terms, headlines, and landing pages. This view shows which search queries triggered your ads and how those specific combinations performed. A future release will include an additional view that also includes Performance Max data. If you want to avoid migrating your implementation to get Performance Max data, consider waiting for that release.
• Added AI_MAX as a new value for the search_term_match_type segment.

Assets:

• Added the fields terms_and_conditions_text, terms_and_conditions_uri, promotion_barcode_info, and promotion_qr_code_info in PromotionAsset. Barcode and QR code fields are located within the promotion_trigger oneof.
• Added FINAL_URL_EXPANSION_TEXT_ASSET_AUTOMATION to AssetAutomationTypeEnum. With this setting, you can control the automatic generation of text assets and landing pages from the final URL in Search campaigns.
• Added a new service AutomaticallyCreatedAssetRemovalService.RemoveCampaignAutomaticallyCreatedAsset to remove automatically created assets from Campaign. This service supports removal of the final URL expansion asset only.
• Added DESCRIPTION_PREFIX to the ServedAssetFieldType enum. This corrects an issue where the served_asset_field_type in ad_group_ad_asset_combination_view was UNKNOWN for assets serving as a description prefix.

Campaigns:

• Added a new enum value MISSING_LOCATION_TARGETING to CampaignPrimaryStatusReason. This new status reason will be returned only for location-restricted campaigns which don't specify location targeting. For location-restricted campaigns, any attempt to add location targeting outside the allowed area will result in the criterion error LOCATION_TARGETING_NOT_ELIGIBLE_FOR_RESTRICTED_CAMPAIGN.
• Added support for third-party integration partners on the VideoCustomer.third_party_integration_partners and Campaign.third_party_integration_partners levels. See the Help Center article Track app conversions with third-party app analytics.
• You can now set the advertising_partner_ids field for an existing Campaign. Previously, this field could only be set for a new campaign during its creation.
• By using a shared list of type TYPE_PLACEMENT_LIST defined at the manager account level, advertisers can now use CustomerNegativeCriterion criteria to exclude a list of placements in individual advertiser customer accounts.
• Added DESCRIPTION_PREFIX to the ServedAssetFieldType enum. This corrects an issue where the served_asset_field_type in the ad_group_ad_asset_combination_view was UNKNOWN for assets serving as a description prefix.
• Added support for the field target_roas_tolerance_percent_millis in the MaximizeConversionValue and TargetRoas bidding strategies. TargetRoas.target_roas_tolerance_percent_millis is only available for portfolio strategies, which is only available for Search campaigns.
• Changed a ProductGroup error code. For requests with a partial failure enabled, LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION will be returned instead of INVALID_LISTING_GROUP_HIERARCHY.
• Added a new resource LocationInterestView that summarizes the performance of adgroup location interest criteria.

Conversions:

• Added ENGAGED_VIEW as a new value for the conversion_attribution_event_type segment.
• Customers will no longer have access to debug_enabled mode in ConversionUploadService. This field, if set to TRUE, was earlier used to distinguish the CLICK_NOT_FOUND error from SUCCESS for enhanced conversions for leads imports.

Demand Gen:

• Added an error code CampaignBudgetError.BUDGET_BELOW_DAILY_MINIMUM. In the future, this error will be returned when attempting to set a very low budget amount for a Demand Gen campaign. Details about the required minimum budget can be found in the new error details field budgetDailyMinimumErrorDetails.

EU political advertising changes:

These EU political advertising changes have also been made in the v19.2 and v20.1 releases.

• Added Campaign.contains_eu_political_advertising. This field indicates whether your campaign contains political advertising content targeted towards the European Union. If this field is set to CONTAINS_EU_POLITICAL_ADVERTISING, the campaign will no longer serve in the EU starting September 22, 2025. API calls to create a new campaign will fail with a FieldError.REQUIRED error if this field is not set. For any existing campaigns, you should set the contains_eu_political_advertising field before attempting to change proximity, location, or location group targeting either at the campaign or ad group levels. The API calls to create or update these campaign or ad group criteria for existing campaigns will fail with a CriterionError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION error if the campaign hasn't completed the self-declaration. For versions v19.x and 20.x, the requirement to set this field is not yet enforced, but will be in the future. This change will be announced in advance.
• Trials and Experiments will throw an ExperimentError.MISSING_EU_POLITICAL_ADVERTISING_SELF_DECLARATION if the experiment's campaigns haven't self-declared whether they contain political advertising that targets the European Union.

Performance Max:

• For new PMax campaigns the default value of Campaign.brand_guidelines_enabled is now true.
• Added the campaign_search_term_view report. This view offers search terms metrics aggregated at the campaign level. This view also introduces Performance Max campaign support for search terms.
• Added PERFORMANCE_MAX as a new value for the search_term_match_type segment.

Planning:

• Added a new method ReachPlanService.ListPlannableUserInterests, which allows advertisers to discover the user interests (affinities and in-markets) supported by ReachPlanService.GenerateReachForecast. The method supports searching for specific user interest types and querying for names and paths.
• Added AdditionalApplicationInfo to ReachPlanService.ListPlannableUserLists as an optional input field.
• Added support to AudienceInsightsService.ListAudienceInsightsAttributes to fetch available 1P user lists for the customer ID making the request.
• Added 1P user lists support to AudienceInsightsService.GenerateAudienceCompositionInsights to fetch insights for audiences targeting a user list. Any request that targets a user list will only return the audience index and is only available for the following AudienceInsightsDimension: AGE_RANGE, GENDER, AFFINITY_USER_INTEREST, IN_MARKET_USER_INTEREST.
• Updated the audience input type to InsightsAudience for AudienceInsightsService.GenerateTargetingSuggestionMetrics. The new audience input allows an AND-of-ORs combination of user interests, supporting potential reach metrics for more customized audience definitions.
• Added audience share to TrendInsightMetrics to get the share of an audience for a trend.
• Added new related categories to KnowledgeGraphAttributeMetadata so users can filter Knowledge Graph Attributes by category.

Reports:

• A variety of new metrics are now available for AssetGroupAsset, ChannelAggregateAssetView, and CampaignAggregateAssetView. Additionally, for ChannelAggregateAssetView and CampaignAggregateAssetView, impressions, which was previously zeroed out for Performance Max campaigns, will now report its true value.
• Made the AssetSet resource selectable with ChangeStatus so users can make get more info about the AssetSet or CampaignAssetSet type resource in one query.
• Made the CampaignAssetSet resource selectable with ChangeStatus so users can make get more info about the AssetSet or CampaignAssetSet type resource in one query.
• Added a new segment search_term_targeting_status that can be selected in campaign search term view.
• Added a new final_url_expansion_asset_view.
• Added support for metrics value_adjustment and all_value_adjustment in the AssetGroup report.
• Made AssetGroupAsset segmentable by ad_network_type.
• Added a new segment landing_page_source that can be used with the landing_page_view resource.
• Added a new segment search_term_match_source that can be selected in the search term and campaign search term views.
• Added a new segment match_type that can be selected from the keyword view.
• Added support for metrics for unique query intent clusters with
• Added a new click type VEHICLE_ASSETS in the click_view segmentation to track and report clicks related to the ad formats specific to vehicle assets.

Video:

• Added YouTubeVideoListAsset. Also added Asset#youtube_video_list_asset, which can be used to create link between a campaign and a YouTubeVideoListAsset type. See the Help Center article Use related videos.
• Added new metadata fields to YouTubeChannelInsights and YouTubeVideoAttributeMetadata.
• Exposed new click types: VIDEO_RELATED_VIDEOS_CLICK, VIDEO_CHANNEL_CLICK, and PRODUCT_ASSETS.
• Added the allow_non_skippable_in_stream field to VideoAdInventoryControl to let Video Responsive ads serve as non-skippable in-stream ads. This option is available for campaigns that support mixing the non-skippable format with other formats.
• Added the Campaign.VideoCampaignSettings.video_ad_sequence and AdGroup.VideoAdGroupSettings.VideoAdSequenceStepSetting fields (read-only). See the Help Center article About video ad sequencing.
• Added new metadata fields to YouTubeChannelInsights and YouTubeVideoAttributeMetadata.
• Added the VIDEO_LINEUP criterion type and the video_lineup field to CampaignCriterion and AdGroupCriterion. This feature is available to allowlisted accounts only. Contact your Google business development representative for details.
• Added a Content Suitability report for both the detail and the group level. See the Help Center article About the 'Content suitability' report.

Forum discussion at X.