---
metadata:
  - name: generator
    content: Diplodoc Platform v5.50.6
alternate:
  - https://yandex.ru/dev/direct/doc/en/objects/adgroup.md
  - https://yandex.ru/dev/direct/doc/ru/objects/adgroup.md
sourcePath: en/dg/objects/adgroup.md
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/en/llms.txt

# Ad group

An ad group consists of a set of ads and shared criteria for displaying these ads. You can use groups to test different variations of ads and automatically determine which of them is the most attractive for the audience. For more information, see [Experimenting with ads](https://yandex.com/support/direct/en/efficiency/ad-groups.html) in Yandex Direct Help.


## Service {#service}

Use the [AdGroups](https://yandex.com/dev/direct/doc/adgroups/adgroups.html) service for managing groups.


### Methods {#methods}

[add](https://yandex.com/dev/direct/doc/adgroups/add.html) | [update](https://yandex.com/dev/direct/doc/adgroups/update.html) | [delete](https://yandex.com/dev/direct/doc/adgroups/delete.html) | [get](https://yandex.com/dev/direct/doc/adgroups/get.html) 

To manage an ad group in a unified performance campaign, use the URL: `https://api.direct.yandex.com/v501/`.


## Restrictions {#restrictions}

The group type must match the campaign type.

Operations with groups are not possible in archived campaigns.

To check the limit on the number of ad groups per campaign, use the [Clients](https://yandex.com/dev/direct/doc/clients/clients.html).[get](https://yandex.com/dev/direct/doc/clients/get.html) or [AgencyClients](https://yandex.com/dev/direct/doc/agencyclients/agencyclients.html).[get](https://yandex.com/dev/direct/doc/agencyclients/get.html) method (look for the ADGROUPS_TOTAL_PER_CAMPAIGN element in the [Restrictions](*Restrictions) array).


## Ad group type {#types}

The group type is set when creating an ad group and can't be changed.

The set of group parameters depends on its type.

The parameters common to all types of groups are the name, display region, shared negative keywords for a group, as well as tags. When creating or editing a group, pass these parameters within the `AdGroups` structure of the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) and [update](https://yandex.com/dev/direct/doc/adgroups/update.html) methods. To get these parameters, list the parameter names in the `FieldNames` input parameter for the [get](https://yandex.com/dev/direct/doc/ads/get.html) method.

The parameters that depend on the group type are passed in the child structure with the corresponding name.

The Yandex Direct API currently supports the following types of groups:

- TEXT_AD_GROUP — A group of Text & Image ads.

    For this type of group, you can additionally specify the feed ID and product category IDs for generating Text & Image ads.

    A group can have child objects — [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md), [keywords](https://yandex.ru/dev/direct/doc/en/objects/keyword.md), [autotargetings](https://yandex.ru/dev/direct/doc/en/best-practice/auto-targeting.md), and [audience targets](https://yandex.ru/dev/direct/doc/en/objects/audience-target.md). [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.

- SMART_AD_GROUP — A group of smart banners.

    For this type of group, you must specify the feed ID to use for generating smart banners. Optionally, you can specify the names of feed elements to take the ad title and text from. For more information about smart banners, see [Smart banners](https://yandex.com/support/direct/en/smart-banners/about.html) in Yandex Direct Help.

    To create or edit a group, use the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) or [update](https://yandex.com/dev/direct/doc/adgroups/update.html) method with the group-specific parameters defined in the `SmartAdGroup` structure.

    When getting group parameters, list the names of parameters that are shared across all group types in the `FieldNames` input parameter, and list the names of parameters that are specific to this group type in the `SmartAdGroupFieldNames` input parameter of the [get](https://yandex.com/dev/direct/doc/adgroups/get.html) method.

    A group can have child objects — [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md). [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.

- MOBILE_APP_AD_GROUP: A group for promoting mobile apps.

    For this type of group, you must additionally specify a link to the app in App Store or Google Play, along with the types of devices, types of internet connection, and earliest OS version that the ad can be displayed on. For more information about promoting mobile apps, see [App promotion](https://yandex.com/support/direct/en/ru/products-mobile-apps-ads/about) in Yandex Direct Help.

    {% note alert %}

    All ad groups in the same campaign must have the same app link.

    {% endnote %}

    To create or edit a group, use the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) or [update](https://yandex.com/dev/direct/doc/adgroups/update.html) method with the group-specific parameters defined in the `MobileAppAdGroup` structure.

    When getting group parameters, list the names of parameters that are shared across all group types in the `FieldNames` input parameter, and list the names of parameters that are specific to this group type in the `MobileAppAdGroupFieldNames` input parameter of the [get](https://yandex.com/dev/direct/doc/adgroups/get.html) method.

    A group can have child objects — [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md), [keywords](https://yandex.ru/dev/direct/doc/en/objects/keyword.md), [autotargetings](https://yandex.ru/dev/direct/doc/en/best-practice/auto-targeting.md), and [audience targets](https://yandex.ru/dev/direct/doc/en/objects/audience-target.md). [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.

- DYNAMIC_TEXT_AD_GROUP — A group of dynamic ads. For more information about dynamic ads, see [Dynamic ads](https://yandex.com/support/direct/en/dynamic-text-ads/about-da.html) in Yandex Direct Help.

    There are two subtypes of dynamic ad groups:

    - WEBPAGE — The data source for generating ads is website pages.

      For this subtype, you must also specify the promoted domain.

      To create or edit a group, use the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) or [update](https://yandex.com/dev/direct/doc/adgroups/update.html) method with the group-specific parameters defined in the `DynamicTextAdGroup` structure.

      When getting group parameters, list the names of parameters that are shared across all group types in the `FieldNames` input parameter, and list the names of parameters that are specific to this group type in the `DynamicTextAdGroupFieldNames` input parameter of the [get](https://yandex.com/dev/direct/doc/adgroups/get.html) method.

      A group can have child objects: [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md). [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.

    - FEED — The data source for generating ads is a feed (a file with product offers).

      When getting group parameters, list the names of parameters that are shared across all group types in the `FieldNames` input parameter, and list the names of parameters that are specific to this group type in the `DynamicTextFeedAdGroupFieldNames` input parameter of the [get](https://yandex.com/dev/direct/doc/adgroups/get.html) method.

      The group can have child objects: [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md) and filters for selecting product offers from the feed. You must use the web interface for managing filters. [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.

- CPM_BANNER_AD_GROUP — A group of display banners.

    It only has the parameters that are common to all types of groups.

    There are two subtypes for display banner groups:

    - KEYWORDS — The group can have child objects: [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md) and [keywords](https://yandex.ru/dev/direct/doc/en/objects/keyword.md). [Bid adjustments](https://yandex.ru/dev/direct/doc/en/objects/bidmodifier.md) can be set for a group.
      To create this type of group, pass an empty `CpmBannerKeywordsAdGroup` structure in the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) method.

    - USER_PROFILE — The group can have child objects: [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md) and [audience targets](https://yandex.ru/dev/direct/doc/en/objects/audience-target.md) by user profile. Negative keywords are not allowed in this type of group.
      To create this type of group, pass an empty `CpmBannerUserProfileAdGroup` structure in the [add](https://yandex.com/dev/direct/doc/adgroups/add.html) method.

- CPM_VIDEO_AD_GROUP: A group of display video ads in a display campaign.

    It only has the parameters that are common to all types of groups. Negative keywords are not allowed in these groups.

    {% note alert %}

    The **Gather audience by completion rate** setting is currently not supported in the API.

    {% endnote %}

    The group can have child objects: [ads](https://yandex.ru/dev/direct/doc/en/objects/ad.md) and [audience targets](https://yandex.ru/dev/direct/doc/en/objects/audience-target.md) by user profile.

- UNIFIED_AD_GROUP — A unified performance group.

    This group can include ads with the following types: `TextAd`, `TextImageAd`, `TextAdBuilderAd`, and `ShoppingAd`. Note that in a unified performance group, you can't specify the following fields for the `TextAd` type:

    - `TurboPageId`;
    - `VCardId`;
    - `Mobile="YES"`;
    - `PreferVCardOverBusiness="YES"`.

    Similarly, you can't specify `TurboPageId` for `TextImageAd` and `TextAdBuilderAd ` types in a unified performance group.

    The group is created with autotargeting disabled in YAN.


## Ad group status {#status}

The `Status` parameter reflects the overall result of reviewing keywords. Keywords are submitted for review automatically when one of the group's ads is submitted for moderation.

#|
|| **Status** | **Description** ||
|| DRAFT | The group has been created but has not yet been submitted for review.  ||
|| MODERATION | The group is under review.  ||
|| PREACCEPTED | The group has been automatically accepted for displays, but will be further reviewed by a moderator.  ||
|| ACCEPTED | At least one of the group's keywords was approved after review (some of them may have been rejected).  ||
|| REJECTED | All keywords were rejected.  ||
|#


## Ad group serving status {#serving-status}

The `ServingStatus` parameter reflects whether the targeting criteria in the group are eligible for ad serving.


#|
|| **Serving status** | **Description** ||
|| ELIGIBLE | Eligible for ad serving. ||
|| RARELY_SERVED | "Rarely served" — With the current settings, ads are rarely served. For example, users don't search for the specified keywords.  ||
|#

[*Restrictions]: **For a user**

Limits on the number of objects for a user.

**For an agency**

—