Google Ads supports a variety of ad types, such as text, image, and mobile ads.
This guide covers how to create, retrieve, and report on ads using Google Ads scripts.
For an overview of all ad types supported by Google Ads, see the
[API guide](https://developers.google.com/google-ads/api/docs/ads/ad-types).

> [!NOTE]
> **Note:** Responsive display ads have gained support for multiple text, image, and video assets in the same ad. Legacy responsive display ads don't support these new features. Both new and legacy ads will continue to serve as usual, but the API for retrieving and manipulating responsive display ads has changed. See [Handling Legacy Responsive Display Ads](https://developers.google.com/google-ads/scripts/docs/ads/responsive-display-ads).

## Creation

Scripts can create ads using the
[`newAd()`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_adgroup#newAd)
method on
[`AdGroup`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_adgroup)
instances. This returns an
[`AdBuilderSpace`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_adbuilderspace)
that creates [builders](https://developers.google.com/google-ads/scripts/docs/concepts/builders) for
supported ad types.

The following snippet demonstrates how to create a responsive search ad:

    let adOperation = adGroup.newAd().responsiveSearchAdBuilder()
        .withHeadlines(["Headline 1", "Headline 2", "Headline 3"])
        .withDescriptions(["Description 1", "Description 2"])
        .withFinalUrl("http://www.example.com")
        .withPath1("path1")
        .withPath2("path2")
        .build();

## Inspection

Some information associated with all ad types is immediately available from an
[`Ad`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_ad), such as an
ad's ID and approval status. Additionally, any ad can be paused, enabled, or
removed.

To access fields specific to an ad's type, such as a responsive search ad's
headlines, use the
[`asType()`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_ad#asType)
method to create an
[`AdViewSpace`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_adviewspace).
This provides access to an extended version of the
[`Ad`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_ad) that exposes
type-specific methods.

The following snippet gets the headlines of every responsive search ad:

    const iterator = AdsApp.ads().withCondition("Type = RESPONSIVE_SEARCH_AD").get();
    while (iterator.hasNext()) {
      let ad = iterator.next();
      let responsiveSearchAd = ad.asType().responsiveSearchAd();
      let headlines = responsiveSearchAd.getHeadlines();
    }

Notice that the condition `Type = RESPONSIVE_SEARCH_AD` ensures every ad from
the iterator is a responsive search ad. Attempting to view an ad with an
incorrect type will result in an error that stops your script's execution, so
it's important to view type-specific fields only when an ad's type is known.

The following snippet shows how to determine if an ad is the correct type
using the
[`Ad.isType()`](https://developers.google.com/google-ads/scripts/docs/reference/adsapp/adsapp_ad#isType)
method:

    if (ad.isType().responsiveSearchAd()) {
      let responsiveSearchAd = ad.asType().responsiveSearchAd();
      let headlines = responsiveSearchAd.getHeadlines();
      let descriptions = responsiveSearchAd.getDescriptions();
    }

While you cannot filter ads by headline text using standard selectors, you can
filter them in JavaScript after retrieving them:

    const iterator = AdsApp.ads().withCondition("Type = RESPONSIVE_SEARCH_AD").get();
    while (iterator.hasNext()) {
      let ad = iterator.next();
      let responsiveSearchAd = ad.asType().responsiveSearchAd();
      let headlines = responsiveSearchAd.getHeadlines();
      // Filter for ads containing a specific headline.
      if (headlines.some(h => h.getText().includes("Special Offer"))) {
        console.log(`Found ad with ID ${ad.getId()}`);
      }
    }

<br />

## Reporting

The [`ad_group_ad` view](https://developers.google.com/google-ads/api/fields/latest/ad_group_ad) can be
used to query ad fields in addition to regular stats. For example, you can
filter on ad type using
[`ad_group_ad.ad.type`](https://developers.google.com/google-ads/api/fields/latest/ad_group_ad#ad_group_ad.ad.type).
The following snippet shows how to retrieve the stats for all responsive search
ads:

    const results = AdsApp.search(
      "SELECT ad_group_ad.ad_group.id, " +
              "ad_group_ad.ad.id, " +
              "metrics.clicks, " +
              "metrics.impressions, " +
              "metrics.cost " +
      "FROM ad_group_ad " +
      "WHERE ad_group_ad.ad.type = 'RESPONSIVE_SEARCH_AD' " +
        "AND segments.date DURING LAST_7_DAYS");

    while (results.hasNext()) {
      let row = results.next();
      let adId = row.adGroupAd.ad.id;
      let clicks = row.metrics.clicks;
      ...
    }

### Filtering by asset content

To filter responsive search ads by the content of their headlines or
descriptions at scale, use the
[`ad_group_ad_asset_view`](https://developers.google.com/google-ads/api/fields/latest/ad_group_ad_asset_view)
resource. This view treats each headline and description as a separate row,
allowing you to filter on the asset's text.

The following snippet retrieves stats for all responsive search ads that
contain a specific headline:

    const results = AdsApp.search(
      "SELECT ad_group_ad.ad.id, " +
              "asset.text_asset.text, " +
              "metrics.clicks, " +
              "metrics.impressions " +
      "FROM ad_group_ad_asset_view " +
      "WHERE asset.text_asset.text LIKE '%Special Offer%' " +
        "AND ad_group_ad_asset_view.field_type = 'HEADLINE'");

    while (results.hasNext()) {
      let row = results.next();
      let adId = row.adGroupAd.ad.id;
      let text = row.asset.textAsset.text;
      let clicks = row.metrics.clicks;
      console.log(`Ad ID ${adId} with headline "${text}" had ${clicks} clicks.`);
    }

See the [reports guide](https://developers.google.com/google-ads/scripts/docs/concepts/reports) for
more information on reporting in scripts.