# REST Resource: advertisers.adGroupAds

> [!WARNING]
> Display \& Video 360 API v3 has sunset. Use [v4](https://developers.google.com/display-video/api/reference/rest/v4) instead.

- [Resource: AdGroupAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdGroupAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdGroupAd.SCHEMA_REPRESENTATION)
- [DisplayVideoSourceAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#DisplayVideoSourceAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#DisplayVideoSourceAd.SCHEMA_REPRESENTATION)
- [MastheadAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#MastheadAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#MastheadAd.SCHEMA_REPRESENTATION)
- [YoutubeVideoDetails](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails.SCHEMA_REPRESENTATION)
- [VideoUnavailableReason](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoUnavailableReason)
- [VideoAspectRatio](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoAspectRatio)
- [InStreamAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#InStreamAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#InStreamAd.SCHEMA_REPRESENTATION)
- [CommonInStreamAttribute](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute.SCHEMA_REPRESENTATION)
- [ImageAsset](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset.SCHEMA_REPRESENTATION)
- [NonSkippableAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#NonSkippableAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#NonSkippableAd.SCHEMA_REPRESENTATION)
- [BumperAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#BumperAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#BumperAd.SCHEMA_REPRESENTATION)
- [AudioAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AudioAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AudioAd.SCHEMA_REPRESENTATION)
- [VideoDiscoveryAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoDiscoveryAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoDiscoveryAd.SCHEMA_REPRESENTATION)
- [Thumbnail](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#Thumbnail)
- [VideoPerformanceAd](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoPerformanceAd)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoPerformanceAd.SCHEMA_REPRESENTATION)
- [AdUrl](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrl)
  - [JSON representation](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrl.SCHEMA_REPRESENTATION)
- [AdUrlType](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrlType)
- [Methods](https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#METHODS_SUMMARY)

## Resource: AdGroupAd

A single ad associated with an ad group.

| JSON representation |
|---|
| ``` { "name": string, "advertiserId": string, "adGroupAdId": string, "adGroupId": string, "displayName": string, "entityStatus": enum (`https://developers.google.com/display-video/api/reference/rest/v3/EntityStatus`), "adUrls": [ { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrl`) } ], // Union field `ad_details` can be only one of the following: "displayVideoSourceAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#DisplayVideoSourceAd`) }, "mastheadAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#MastheadAd`) }, "inStreamAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#InStreamAd`) }, "nonSkippableAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#NonSkippableAd`) }, "bumperAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#BumperAd`) }, "audioAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AudioAd`) }, "videoDiscoverAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoDiscoveryAd`) }, "videoPerformanceAd": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoPerformanceAd`) } // End of list of possible types for union field `ad_details`. } ``` |

| Fields ||
|---|---|
| `name` | `string` The resource name of the ad. |
| `advertiserId` | `string (https://developers.google.com/discovery/v1/type-format format)` The unique ID of the advertiser the ad belongs to. |
| `adGroupAdId` | `string (https://developers.google.com/discovery/v1/type-format format)` The unique ID of the ad. Assigned by the system. |
| `adGroupId` | `string (https://developers.google.com/discovery/v1/type-format format)` The unique ID of the ad group that the ad belongs to. |
| `displayName` | `string` The display name of the ad. Must be UTF-8 encoded with a maximum size of 255 bytes. |
| `entityStatus` | ``enum (`https://developers.google.com/display-video/api/reference/rest/v3/EntityStatus`)`` The entity status of the ad. |
| `adUrls[]` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrl`)`` List of URLs used by the ad. |
| Union field `ad_details`. The details of the ad. `ad_details` can be only one of the following: ||
| `displayVideoSourceAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#DisplayVideoSourceAd`)`` Details of an ad sourced from a Display \& Video 360 creative. |
| `mastheadAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#MastheadAd`)`` Details of an [ad served on the YouTube Home feed](https://support.google.com/google-ads/answer/9709826). |
| `inStreamAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#InStreamAd`)`` Details of an [in-stream ad skippable after 5 seconds](https://support.google.com/displayvideo/answer/6274216), used for brand awareness or reach marketing objectives. |
| `nonSkippableAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#NonSkippableAd`)`` Details of a [non-skippable short in-stream video ad](https://support.google.com/displayvideo/answer/6274216), between 6 and 15 seconds, used for reach marketing objectives. |
| `bumperAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#BumperAd`)`` Details of a [non-skippable short video ad](https://support.google.com/displayvideo/answer/6274216), equal to or less than 6 seconds, used for reach. |
| `audioAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AudioAd`)`` Details of an [audio ad](https://support.google.com/displayvideo/answer/6274216) used for reach marketing objectives. |
| `videoDiscoverAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoDiscoveryAd`)`` Details of an [ad promoting a video](https://support.google.com/displayvideo/answer/6274216) that shows in places of discovery. |
| `videoPerformanceAd` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoPerformanceAd`)`` Details of an [ad used in a video action campaign](https://support.google.com/google-ads/answer/10147229) to drive actions to the business, service or product. |

## DisplayVideoSourceAd

The ad sourced from a DV360 creative.

| JSON representation |
|---|
| ``` { "creativeId": string } ``` |

| Fields ||
|---|---|
| `creativeId` | `string (https://developers.google.com/discovery/v1/type-format format)` The ID of the source creative. |

## MastheadAd

Details for a Masthead Ad.

| JSON representation |
|---|
| ``` { "video": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) }, "headline": string, "description": string, "videoAspectRatio": enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoAspectRatio`), "autoplayVideoStartMillisecond": string, "autoplayVideoDuration": string, "callToActionButtonLabel": string, "callToActionFinalUrl": string, "callToActionTrackingUrl": string, "showChannelArt": boolean, "companionYoutubeVideos": [ { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) } ] } ``` |

| Fields ||
|---|---|
| `video` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The YouTube video used by the ad. |
| `headline` | `string` The headline of the ad. |
| `description` | `string` The description of the ad. |
| `videoAspectRatio` | ``enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoAspectRatio`)`` The aspect ratio of the autoplaying YouTube video on the Masthead. |
| `autoplayVideoStartMillisecond` | `string (https://developers.google.com/discovery/v1/type-format format)` The amount of time in milliseconds after which the video will start to play. |
| `autoplayVideoDuration` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` The duration of time the video will autoplay. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |
| `callToActionButtonLabel` | `string` The text on the call-to-action button. |
| `callToActionFinalUrl` | `string` The destination URL for the call-to-action button. |
| `callToActionTrackingUrl` | `string` The tracking URL for the call-to-action button. |
| `showChannelArt` | `boolean` Whether to show a background or banner that appears at the top of a YouTube page. |
| `companionYoutubeVideos[]` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The videos that appear next to the Masthead Ad on desktop. Can be no more than two. |

## YoutubeVideoDetails

Details of a YouTube video.

| JSON representation |
|---|
| ``` { "id": string, "unavailableReason": enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoUnavailableReason`) } ``` |

| Fields ||
|---|---|
| `id` | `string` The YouTube video ID which can be searched on YouTube webpage. |
| `unavailableReason` | ``enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#VideoUnavailableReason`)`` The reason why the video data is not available. |

## VideoUnavailableReason

Possible reasons why a video could be unavailable.

| Enums ||
|---|---|
| `VIDEO_UNAVAILABLE_REASON_UNSPECIFIED` | Unknown or unspecified. |
| `VIDEO_UNAVAILABLE_REASON_PRIVATE` | The video is private. |
| `VIDEO_UNAVAILABLE_REASON_DELETED` | The video is deleted. |

## VideoAspectRatio

Possible aspect ratios for a YouTube video.

| Enums ||
|---|---|
| `VIDEO_ASPECT_RATIO_UNSPECIFIED` | Not specified or unknown. |
| `VIDEO_ASPECT_RATIO_WIDESCREEN` | The video is stretched and the top and bottom are cropped. |
| `VIDEO_ASPECT_RATIO_FIXED_16_9` | The video uses a fixed 16:9 aspect ratio. |

## InStreamAd

Details for an in-stream ad.

| JSON representation |
|---|
| ``` { "commonInStreamAttribute": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`) }, "customParameters": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `commonInStreamAttribute` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`)`` Common ad attributes. |
| `customParameters` | `map (key: string, value: string)` The custom parameters to pass custom values to tracking URL template. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

## CommonInStreamAttribute

Common attributes for in-stream, non-skippable and bumper ads.

| JSON representation |
|---|
| ``` { "displayUrl": string, "finalUrl": string, "trackingUrl": string, "actionButtonLabel": string, "actionHeadline": string, "video": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) }, "companionBanner": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset`) } } ``` |

| Fields ||
|---|---|
| `displayUrl` | `string` The webpage address that appears with the ad. |
| `finalUrl` | `string` The URL address of the webpage that people reach after they click the ad. |
| `trackingUrl` | `string` The URL address loaded in the background for tracking purposes. |
| `actionButtonLabel` | `string` The text on the call-to-action button. |
| `actionHeadline` | `string` The headline of the call-to-action banner. |
| `video` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The YouTube video of the ad. |
| `companionBanner` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset`)`` The image which shows next to the video ad. |

## ImageAsset

Meta data of an image asset.

| JSON representation |
|---|
| ``` { "mimeType": string, "fullSize": { object (`https://developers.google.com/display-video/api/reference/rest/v3/Dimensions`) }, "fileSize": string } ``` |

| Fields ||
|---|---|
| `mimeType` | `string` MIME type of the image asset. |
| `fullSize` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/Dimensions`)`` Metadata for this image at its original size. |
| `fileSize` | `string (https://developers.google.com/discovery/v1/type-format format)` File size of the image asset in bytes. |

## NonSkippableAd

Details for a non-skippable ad.

| JSON representation |
|---|
| ``` { "commonInStreamAttribute": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`) }, "customParameters": { string: string, ... } } ``` |

| Fields ||
|---|---|
| `commonInStreamAttribute` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`)`` Common ad attributes. |
| `customParameters` | `map (key: string, value: string)` The custom parameters to pass custom values to tracking URL template. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

## BumperAd

Details for a bumper ad.

| JSON representation |
|---|
| ``` { "commonInStreamAttribute": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`) } } ``` |

| Fields ||
|---|---|
| `commonInStreamAttribute` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#CommonInStreamAttribute`)`` Common ad attributes. |

## AudioAd

Details for an audio ad.

| JSON representation |
|---|
| ``` { "displayUrl": string, "finalUrl": string, "trackingUrl": string, "video": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) } } ``` |

| Fields ||
|---|---|
| `displayUrl` | `string` The webpage address that appears with the ad. |
| `finalUrl` | `string` The URL address of the webpage that people reach after they click the ad. |
| `trackingUrl` | `string` The URL address loaded in the background for tracking purposes. |
| `video` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The YouTube video of the ad. |

## VideoDiscoveryAd

Details for a video discovery ad.

| JSON representation |
|---|
| ``` { "headline": string, "description1": string, "description2": string, "video": { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) }, "thumbnail": enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#Thumbnail`) } ``` |

| Fields ||
|---|---|
| `headline` | `string` The headline of ad. |
| `description1` | `string` First text line for the ad. |
| `description2` | `string` Second text line for the ad. |
| `video` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The YouTube video the ad promotes. |
| `thumbnail` | ``enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#Thumbnail`)`` Thumbnail image used in the ad. |

## Thumbnail

Possible thumbnail options in Video Discovery Ads.

| Enums ||
|---|---|
| `THUMBNAIL_UNSPECIFIED` | Unknown or unspecified. |
| `THUMBNAIL_DEFAULT` | The default thumbnail, can be auto-generated or user-uploaded. |
| `THUMBNAIL_1` | Thumbnail 1, generated from the video. |
| `THUMBNAIL_2` | Thumbnail 2, generated from the video. |
| `THUMBNAIL_3` | Thumbnail 3, generated from the video. |

## VideoPerformanceAd

Details for a video performance ad.

| JSON representation |
|---|
| ``` { "finalUrl": string, "trackingUrl": string, "actionButtonLabels": [ string ], "headlines": [ string ], "longHeadlines": [ string ], "descriptions": [ string ], "displayUrlBreadcrumb1": string, "displayUrlBreadcrumb2": string, "domain": string, "videos": [ { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`) } ], "customParameters": { string: string, ... }, "companionBanners": [ { object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset`) } ] } ``` |

| Fields ||
|---|---|
| `finalUrl` | `string` The URL address of the webpage that people reach after they click the ad. |
| `trackingUrl` | `string` The URL address loaded in the background for tracking purposes. |
| `actionButtonLabels[]` | `string` The list of text assets shown on the call-to-action button. |
| `headlines[]` | `string` The list of headlines shown on the call-to-action banner. |
| `longHeadlines[]` | `string` The list of lone headlines shown on the call-to-action banner. |
| `descriptions[]` | `string` The list of descriptions shown on the call-to-action banner. |
| `displayUrlBreadcrumb1` | `string` The first piece after the domain in the display URL. |
| `displayUrlBreadcrumb2` | `string` The second piece after the domain in the display URL. |
| `domain` | `string` The domain of the display URL. |
| `videos[]` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#YoutubeVideoDetails`)`` The list of YouTube video assets used by this ad. |
| `customParameters` | `map (key: string, value: string)` The custom parameters to pass custom values to tracking URL template. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `companionBanners[]` | ``object (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#ImageAsset`)`` The list of companion banners used by this ad. |

## AdUrl

Additional URLs related to the ad, including beacons.

| JSON representation |
|---|
| ``` { "type": enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrlType`), "url": string } ``` |

| Fields ||
|---|---|
| `type` | ``enum (`https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds#AdUrlType`)`` The type of the Ad URL. |
| `url` | `string` The URL string value. |

## AdUrlType

Possible ad URL types.

| Enums ||
|---|---|
| `AD_URL_TYPE_UNSPECIFIED` | Unknown or unspecified. |
| `AD_URL_TYPE_BEACON_IMPRESSION` | A 1x1 tracking pixel to ping when an impression of a creative is delivered. |
| `AD_URL_TYPE_BEACON_EXPANDABLE_DCM_IMPRESSION` | Expandable DCM impression beacon. At serving time, it is expanded to several beacons. |
| `AD_URL_TYPE_BEACON_CLICK` | Tracking URL to ping when the click event is triggered. |
| `AD_URL_TYPE_BEACON_SKIP` | Tracking URL to ping when the skip event is triggered. |

| ## Methods ||
|---|---|
| ### `https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds/get` | Gets an ad group ad. |
| ### `https://developers.google.com/display-video/api/reference/rest/v3/advertisers.adGroupAds/list` | Lists ad group ads. |