Video campaigns

Page Summary

• The Google Ads API only supports fetching and reporting on existing Video campaigns and their criteria.

• You cannot create new Video campaigns or update existing ones using the Google Ads API.

• Google Ads scripts and Demand Gen campaigns are alternatives for programmatic Video campaign management.

• You can retrieve performance data for Video campaigns using GoogleAdsService.SearchStream and filtering by campaign.advertising_channel_type = 'VIDEO'.

Video campaigns let you show video ads on YouTube and across websites and apps running on Google video partners.

API limitations

The Google Ads API primarily supports fetching and reporting on existing Video campaigns, ad groups, ads, and criteria. Video campaigns cannot be created or mutated using the Google Ads API, with the following version-specific exceptions and behaviors:

• VideoResponsiveAdInfo mutability: Starting in v24, VideoResponsiveAdInfo objects are mutable (in earlier versions, they are immutable). When creating or mutating VideoResponsiveAdInfo, the videos, business_name, and logo_images fields are required.
• Brand safety suitability: Starting in v24, campaign-level campaign.video_brand_safety_suitability is removed. Query brand safety suitability at the account level using customer.video_brand_safety_suitability.
• Video campaign experiments: Starting in v24, experiment.video_experiment is available for configuring YOUTUBE_CUSTOM experiments consisting of Video campaigns.

Alternatives for campaign management

If you need to create or manage Video campaigns programmatically, consider the following options:

• Google Ads scripts: You can manage Video campaigns using Google Ads scripts. This allows for automated management within the Google Ads interface.
• Demand Gen campaigns: If your goal is to serve video ads across Google properties including YouTube, Demand Gen campaigns are fully supported in the Google Ads API for both creation and management.

Get performance data

You can retrieve performance data for your Video campaigns, ad groups, and criteria using GoogleAdsService.SearchStream by filtering for campaign.advertising_channel_type = 'VIDEO'.

Note: Use metrics.video_trueview_views, metrics.video_trueview_view_rate, and metrics.trueview_average_cpv for TrueView view metrics. Starting in v25, you can also select segments.ad_sub_format_type (alongside segments.ad_format_type) to break down non-skippable in-stream ads by duration, as well as video social engagement metrics (metrics.youtube_comments, metrics.youtube_likes, and metrics.youtube_shares).

Ad group performance

The following query retrieves Video campaign and ad group metrics, including TrueView video views and quartile completion rates, from the ad_group resource:

SELECT
  campaign.id,
  campaign.name,
  campaign.advertising_channel_type,
  ad_group.id,
  ad_group.name,
  metrics.impressions,
  metrics.clicks,
  metrics.ctr,
  metrics.video_trueview_views,
  metrics.video_quartile_p100_rate
FROM ad_group
WHERE campaign.advertising_channel_type = 'VIDEO'

Video placement and criteria reporting

Because ad_group_criterion does not support metrics or segments directly, use criteria view resources such as managed_placement_view to retrieve performance metrics for targeted YouTube videos, YouTube channels, or other managed placements:

SELECT
  campaign.id,
  ad_group.id,
  ad_group_criterion.criterion_id,
  ad_group_criterion.type,
  ad_group_criterion.youtube_video.video_id,
  ad_group_criterion.youtube_channel.channel_id,
  metrics.impressions,
  metrics.video_trueview_views
FROM managed_placement_view
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND ad_group_criterion.type IN ('YOUTUBE_VIDEO', 'YOUTUBE_CHANNEL')
  AND segments.date DURING LAST_30_DAYS

Campaign reach and frequency reporting

For Video campaigns, you can query Unique Reach metrics on the campaign resource to measure the number of unique individuals who were shown your ads at specific impression frequencies.

The following unique user metrics measure audience reach across frequency buckets:

• metrics.unique_users: The number of unique people who saw your ad at least once within the selected date range (up to 92 days). It can't be aggregated across rows.
• metrics.unique_users_two_plus through metrics.unique_users_ten_plus: The number of unique people who saw your ad at least 2 through 10 times, respectively, for date ranges of up to 31 days (with metrics.unique_users_six_plus through metrics.unique_users_nine_plus completing the 2+ through 10+ set in v26 and later).
• metrics.average_impression_frequency_per_user: The average number of times a unique user saw your ad during the requested period (up to 92 days). It can't be aggregated across rows and doesn't have a companion _info field.

In v26 and later, each reach metric has a companion metadata field of type ReachMetricInfo: metrics.unique_users_info and metrics.unique_users_two_plus_info through metrics.unique_users_ten_plus_info.

In Google Ads Query Language (GAQL), companion reach fields are MESSAGE metrics selected directly in the SELECT clause (for example, metrics.unique_users_info). Don't append .reach_metric_states in the SELECT clause, because selecting nested message fields in GAQL fails with UNRECOGNIZED_FIELD. Instead, selecting metrics.unique_users_info returns a ReachMetricInfo message containing the repeated enum field reach_metric_states of type ReachMetricState, which describes whether the metric was suppressed or is complete.

Whenever a reach metric is suppressed or outside the retention window (PRIVACY_SUPPRESSION, QUALITY_SUPPRESSION, or DATE_RANGE_BEYOND_RETENTION), its optional int64 field on Metrics is unset (which evaluates to 0 if field presence isn't checked), whereas LOW_QUALITY still populates the numeric metric.

The ReachMetricState enum values indicate the status of the reach data:

• COMPLETE: The reach metric is complete with no suppression due to privacy, quality, or other limits.
• PRIVACY_SUPPRESSION: Reach data was suppressed to protect user privacy (for example, when audience volume doesn't meet k-anonymity thresholds).
• QUALITY_SUPPRESSION: Reach data was suppressed due to data quality requirements.
• LOW_QUALITY: The reach metric was calculated but is flagged as low quality.
• DATE_RANGE_BEYOND_RETENTION: Reach metrics are unavailable because the selected date range exceeds the 3-year data retention period for reach data.

The following query retrieves reach metrics and their suppression states for a Video campaign:

SELECT
  campaign.id,
  campaign.name,
  segments.date,
  segments.device,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.average_impression_frequency_per_user,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_three_plus,
  metrics.unique_users_three_plus_info,
  metrics.unique_users_four_plus,
  metrics.unique_users_four_plus_info,
  metrics.unique_users_five_plus,
  metrics.unique_users_five_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_seven_plus,
  metrics.unique_users_seven_plus_info,
  metrics.unique_users_eight_plus,
  metrics.unique_users_eight_plus_info,
  metrics.unique_users_nine_plus,
  metrics.unique_users_nine_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date BETWEEN '2026-01-01' AND '2026-01-31'

Note: Reach and frequency metrics can't be aggregated across rows. While metrics.unique_users and metrics.average_impression_frequency_per_user support date ranges of up to 92 days and can be segmented by segments.date, segments.device, segments.adjusted_age_range, and segments.adjusted_gender, the unique_users_*_plus frequency bucket metrics (up to 31 days) and all companion metrics.unique_users*_info fields only support segments.date and segments.device. In addition, companion metrics.unique_users*_info fields are MESSAGE metrics with filterable: false and sortable: false, so they can't be used in WHERE or ORDER BY clauses. See Reach metric suppression and zero values for more details on handling suppressed reach metrics in reports.