[Video campaigns](https://support.google.com/google-ads/answer/2375497) 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/VideoResponsiveAdInfo.md.txt) 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/Customer.md.txt#video_brand_safety_suitability).
- **Video campaign experiments** : Starting in v24, [`experiment.video_experiment`](https://developers.google.com/google-ads/api/reference/rpc/v26/Experiment.md.txt#video_experiment) is available for configuring [`YOUTUBE_CUSTOM`](https://developers.google.com/google-ads/api/reference/rpc/v26/ExperimentTypeEnum.ExperimentType.md.txt#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](https://developers.google.com/google-ads/scripts/docs/campaigns/video-campaigns.md.txt). 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](https://developers.google.com/google-ads/api/docs/demand-gen/overview.md.txt) 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream.md.txt) by filtering for
`campaign.advertising_channel_type = 'VIDEO'`.

> [!NOTE]
> **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:

```sql
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`](https://developers.google.com/google-ads/api/fields/v26/managed_placement_view.md.txt) to retrieve
performance metrics for targeted YouTube videos, YouTube channels, or other
managed placements:

```sql
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
```

### Reach and frequency reporting

For Video campaigns, you can query Unique Reach metrics on the `campaign` and
`customer` (starting in v26) resources 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`](https://developers.google.com/google-ads/api/reference/rpc/v26/Metrics.md.txt#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`](https://developers.google.com/google-ads/api/reference/rpc/v26/Metrics.md.txt#average_impression_frequency_per_user): The average number of times a unique user saw your ad during the requested period (up to 92 days). This metric is available only on the `campaign` resource, can't be aggregated across rows, and doesn't have a companion `_info` field.

In v26 and later, each unique user reach metric has a companion metadata
field of type [`ReachMetricInfo`](https://developers.google.com/google-ads/api/reference/rpc/v26/ReachMetricInfo):
[`metrics.unique_users_info`](https://developers.google.com/google-ads/api/reference/rpc/v26/Metrics.md.txt#unique_users_info) and
`metrics.unique_users_two_plus_info` through
`metrics.unique_users_ten_plus_info`.

In [Google Ads Query Language (GAQL)](https://developers.google.com/google-ads/api/docs/query/structure.md.txt), companion `metrics.unique_users*_info`
fields are `MESSAGE` metrics with `filterable: false` and `sortable: false`, so
you can't use them in `WHERE` or `ORDER BY` clauses. Select these fields
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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ReachMetricInfo) message containing the repeated enum
field `reach_metric_states` of type [`ReachMetricState`](https://developers.google.com/google-ads/api/reference/rpc/v26/ReachMetricStateEnum.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`](https://developers.google.com/google-ads/api/reference/rpc/v26/ReachMetricStateEnum.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 30-day deduplicated reach metrics and their
suppression states for Video campaigns, segmented by device and ad format.
Omit the `segments.date` segment from the `SELECT` clause so that reach and
`N+` frequency metrics are deduplicated across the full date window rather
than per day:

```sql
SELECT
  campaign.id,
  campaign.name,
  segments.device,
  segments.ad_format_type,
  segments.ad_sub_format_type,
  metrics.unique_users,
  metrics.unique_users_info,
  metrics.unique_users_two_plus,
  metrics.unique_users_two_plus_info,
  metrics.unique_users_six_plus,
  metrics.unique_users_six_plus_info,
  metrics.unique_users_ten_plus,
  metrics.unique_users_ten_plus_info
FROM campaign
WHERE campaign.advertising_channel_type = 'VIDEO'
  AND segments.date DURING LAST_30_DAYS
```

#### Supported resources, date windows, and segments

Reach and frequency queries require a finite `segments.date` filter within the
metric's maximum date window. Queries without a date filter or exceeding the
window return unset reach fields:

| Metric | Resources | Max date range | Compatible segments |
|---|---|---|---|
| `metrics.unique_users` | `campaign`, `customer` (v26 and later) | 92 days | `segments.date`, `segments.device`, ad format segments (v26 and later), ad network segments (v26 and later), and adjusted demographic segments |
| `metrics.average_impression_frequency_per_user` | `campaign` | 92 days | `segments.date`, `segments.device`, and adjusted demographic segments |
| `metrics.unique_users_two_plus` through `metrics.unique_users_ten_plus` | `campaign`, `customer` (v26 and later) | 31 days | `segments.date`, `segments.device`, ad format segments (v26 and later), and ad network segments (v26 and later) |
| `metrics.unique_users*_info` (v26 and later) | `campaign`, `customer` | Matches base metric | `segments.date`, `segments.device`, ad format segments, and ad network segments |

When segmenting reach queries, apply the following [joint segment
constraints](https://developers.google.com/google-ads/api/docs/reporting/segmentation#joint-segment-constraints):

- **Ad format versus ad network segments** : You can segment by ad format (`segments.ad_format_type`, optionally with `segments.ad_sub_format_type`) or by ad network (`segments.ad_network_type`, optionally with `segments.ad_sub_network_type`), but you can't combine ad format and ad network segments in the same query. Always select the parent segment (`segments.ad_format_type` or `segments.ad_network_type`) when selecting its sub-segment. The `segments.ad_sub_format_type` segment breaks down non-skippable in-stream ads by duration and returns `UNSEGMENTED` for other ad formats, while the `segments.ad_sub_network_type` segment breaks down YouTube surfaces (`YOUTUBE_INSTREAM`, `YOUTUBE_INFEED`, and `YOUTUBE_SHORTS`) only for Demand Gen campaigns and returns `UNSEGMENTED` for Video campaigns.
- **Adjusted demographic segments** : The `segments.adjusted_age_range` and `segments.adjusted_gender` segments are available only to allowlisted accounts, must be selected together, and can't be combined with `metrics.unique_users_*_plus` metrics, `metrics.unique_users*_info` fields, or ad network segments.

> [!NOTE]
> **Note:** Reach and frequency metrics can't be aggregated across rows. On the `customer` resource, `campaign` fields aren't filterable, and unique user reach metrics deduplicate reach across all supported campaign types in the account. See [Reach metric suppression and zero values](https://developers.google.com/google-ads/api/docs/reporting/zero-metrics.md.txt#reach-suppression) for more details.