--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://yandex.ru/dev/direct/doc/en/adgroups/get.md - https://yandex.ru/dev/direct/doc/ru/adgroups/get.md sourcePath: ru/ref-v5/adgroups/get.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/direct/doc/ru/llms.txt # get Возвращает параметры групп, отвечающих заданным критериям. ## Узнайте больше - [Как работает метод get](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html) ## Ограничения {#restrictions} Для работы с Единой перфоманс-группой используется адрес `https://api.direct.yandex.com/v501/`. Метод возвращает не более 10 000 объектов. ## Запрос {#input} Структура запроса в формате JSON: ```javascript translate=no { "method": "get", "params": { /* params */ "SelectionCriteria": { /* AdGroupsSelectionCriteria */ "CampaignIds": [(long), ... ], "Ids": [(long), ... ], "Types": [( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" | "CPM_BANNER_AD_GROUP" | "CPM_VIDEO_AD_GROUP" | "SMART_AD_GROUP" | "UNIFIED_AD_GROUP" ), ... ], "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), ... ], "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ], "AppIconStatuses": [( "ACCEPTED" | "MODERATION" | "REJECTED" ), ... ], "NegativeKeywordSharedSetIds": [(long), ... ] }, /* required */ "FieldNames": [( "CampaignId" | ... | "Type" ), ... ], /* required */ "MobileAppAdGroupFieldNames": [( "StoreUrl" | ... | "AppIconModeration" ), ... ], "DynamicTextAdGroupFieldNames": [( "DomainUrl" | "DomainUrlProcessingStatus" | "AutotargetingCategories" ), ... ], "DynamicTextFeedAdGroupFieldNames": [( "Source" | "FeedId" | "SourceType" | "SourceProcessingStatus" | "AutotargetingCategories" ), ... ], "SmartAdGroupFieldNames": [( "FeedId" | "AdTitleSource" | "AdBodySource" ), ... ], "TextAdGroupFeedParamsFieldNames": [ ( "FeedId" | "FeedCategoryIds" ) ], "UnifiedAdGroupFieldNames" : [ ("OfferRetargeting") ], "Page": { /* LimitOffset */ "Limit": (long), "Offset": (long) } } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || **Структура params (для JSON) / GetRequest (для SOAP)** | > | > | > || || `SelectionCriteria` | AdGroupsSelectionCriteria | Критерий отбора групп. | Да || || `FieldNames` | array of AdGroupFieldEnum | Имена параметров верхнего уровня, которые требуется получить. | Да || || `MobileAppAdGroupFieldNames` | array of MobileAppAdGroupFieldEnum | Имена параметров группы для продвижения мобильных приложений, которые требуется получить. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `MobileAppAdGroupFieldNames` не возвращаются. {% endnote %} | Нет || || `DynamicTextAdGroupFieldNames` | array of DynamicTextAdGroupFieldEnum | Имена параметров группы динамических объявлений, для которых источником данных является сайт. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `DynamicTextAdGroupFieldNames` не возвращаются. {% endnote %} | Нет || || `DynamicTextFeedAdGroupFieldNames` | array of DynamicTextFeedAdGroupFieldEnum | Имена параметров группы динамических объявлений, для которых источником данных является фид. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `DynamicTextFeedAdGroupFieldNames` не возвращаются. {% endnote %} | Нет || || `SmartAdGroupFieldNames` | array of SmartAdGroupFieldEnum | Имена параметров группы смарт-баннеров. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `SmartAdGroupFieldNames` не возвращаются. {% endnote %} | Нет || || `TextAdGroupFeedParamsFieldNames` | array of TextAdGroupFeedParamsFieldEnum | Имена параметров группы текстово-графических объявлений, для которых источником данных является фид. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `TextAdGroupFeedParamsFieldNames` не возвращаются. {% endnote %} | Нет || || `UnifiedAdGroupFieldNames` | array of UnifiedAdGroupFieldEnum | Имена параметров единой перфоманс группы. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). {% note info %} Если согласно `SelectionCriteria` отобрана группа другого типа, параметры из `UnifiedAdGroupFieldNames` не возвращаются. {% endnote %} | Нет || || `Page` | LimitOffset | Структура, задающая страницу при [постраничной выборке](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html#page) данных. | Нет || || **Структура AdGroupsSelectionCriteria** | > | > | > || || `CampaignIds` | array of long | Отбирать группы указанных кампаний. От 1 до 10 элементов в массиве. | Хотя бы один из параметров `CampaignIds` и `Ids` (могут присутствовать оба) || || `Ids` | array of long | Отбирать группы с указанными идентификаторами. От 1 до 10 000 элементов в массиве. | ^ || || `Types` | array of AdGroupTypesEnum | Отбирать группы с указанными типами. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). | Нет || || `Statuses` | array of AdGroupStatusSelectionEnum | Отбирать группы с указанными статусами. См. [Статус группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#status). | Нет || || `ServingStatuses` | array of ServingStatusEnum | Отбирать группы с указанными статусами возможности показов. См. [Статус возможности показов группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#serving-status). | Нет || || `AppIconStatuses` | array of AdGroupAppIconStatusSelectionEnum | Отбирать группы по результату модерации иконки приложения: - ACCEPTED — принята модерацией; - MODERATION — находится на модерации; - REJECTED — отклонена. Если параметр задан, будут получены только группы для продвижения мобильных приложений. Не следует задавать его, если требуется получить группы других типов. | Нет || || `NegativeKeywordSharedSetIds` | array of long | Отбирать группы объявлений, в которых используется хотя бы один из указанных наборов минус-фраз. | Нет || |# ## Ответ {#output} Структура ответа в формате JSON: ```javascript translate=no { "result": { /* result */ "AdGroups": [{ /* AdGroupGetItem */ "Id": (long), "Name": (string), "CampaignId": (long), "RegionIds": [(long), ... ], "RestrictedRegionIds": { /* ArrayOfLong */ "Items": [(long), ... ] /* required */ }, /* nillable */ "NegativeKeywords": { /* ArrayOfString */ "Items": [(string), ... ] /* required */ }, /* nillable */ "NegativeKeywordSharedSetIds": { /* ArrayOfLong */ "Items": [(long), ... ] /* required */ }, /* nillable */ "TrackingParams": (string), "Status": ( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ), "Type": ( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" | "CPM_BANNER_AD_GROUP" | "CPM_VIDEO_AD_GROUP" | "SMART_AD_GROUP" ), "Subtype": ( "WEBPAGE" | "FEED" | "NONE" | "KEYWORDS" | "USER_PROFILE" ), "MobileAppAdGroup": { /* MobileAppAdGroupGet */ "StoreUrl": (string), "TargetDeviceType": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ], "TargetCarrier": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ), "TargetOperatingSystemVersion": (string), "AppIconModeration": { /* ExtensionModeration */ "Status": ( "ACCEPTED" | "MODERATION" | "REJECTED" ), /* required */ "StatusClarification": (string) }, /* nillable */ "AppOperatingSystemType": ( "IOS" | "ANDROID" | "OS_TYPE_UNKNOWN" ), "AppAvailabilityStatus": ( "UNPROCESSED" | "AVAILABLE" | "NOT_AVAILABLE" ) }, "DynamicTextAdGroup": [{ /* DynamicTextAdGroupGet */ "DomainUrl": (string), "DomainUrlProcessingStatus": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" ), "AutotargetingCategories" : { /* nillable */ "Items" : [{ /* required */ "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */, "Value" : ("YES"|"NO") /* required */ }, ...] }, ...] }, ...], "DynamicTextFeedAdGroup": [{ /* DynamicTextFeedAdGroupGet */ "Source": (string), "FeedId": (long), "SourceType": ( "RETAIL_FEED" | "UNKNOWN" ), "SourceProcessingStatus": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" ), "AutotargetingCategories" : { /* nillable */ "Items" : [{ /* required */ "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */, "Value" : ("YES"|"NO") /* required */ }, ...] }, ...] }, ...], "SmartAdGroup": { /* SmartAdGroupGet */ "FeedId": (long), "AdTitleSource": (string), /* nillable */ "AdBodySource": (string) /* nillable */ }, "TextAdGroupFeedParams" : { /* TextAdGroupFeedParamsGet */ "FeedId" : (long) /* nillable */, "FeedCategoryIds" : { /* nillable */ "Items" : [ (long) ] /* required */ } }, "UnifiedAdGroup" : { "OfferRetargeting" : ("YES"|"NO") } }, ... ], "LimitedBy": (long) } } ``` #| || **Параметр** | **Тип** | **Описание** || || **Структура result (для JSON) / GetResponse (для SOAP)** | > | > || || `AdGroups` | array of AdGroupGetItem | Группы объявлений. || || `LimitedBy` | long | Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел [Постраничная выборка](https://yandex.ru/dev/direct/doc/dg/best-practice/get.html#page). || || **Структура AdGroupGetItem** | > | > || || `Id` | long | Идентификатор группы объявлений. || || `Name` | string | Название группы. || || `CampaignId` | long | Идентификатор кампании. || || `RegionIds` | array of long | Идентификаторы регионов, для которых показы включены или выключены. Идентификатор 0 — показывать во всех регионах. Минус перед идентификатором региона — выключить показы в данном регионе. Например [1,-219] — показывать для Москвы и Московской области, кроме Черноголовки. || || `RestrictedRegionIds` | ArrayOfLong, nillable | Идентификаторы регионов, в которых объявления не будут показаны в связи с законодательными ограничениями. || || `NegativeKeywords` | ArrayOfString, nillable | Минус-фразы, общие для всех ключевых фраз группы объявлений. || || `NegativeKeywordSharedSetIds` | ArrayOfLong, nillable | Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве. || || `TrackingParams` | string | GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать [подстановочные переменные](https://yandex.ru/support/direct/statistics/url-tags.html). Например: from=direct&ad=\{ad_id\} Параметр можно указать для групп текстово-графических объявлений, динамических объявлений и смарт-баннеров, но в настоящее время он используется только для групп динамических объявлений и смарт-баннеров. || || `Status` | StatusEnum | Статус группы. См. [Статус группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#status). || || `ServingStatus` | ServingStatusEnum | Статус возможности показов группы. См. [Статус возможности показов группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#serving-status). || || `Type` | AdGroupTypesEnum | Тип группы объявлений. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). || || `Subtype` | AdGroupSubtypeEnum | Подтип группы объявлений. Для групп с типом, отличным от DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP, возвращается значение NONE. || || `MobileAppAdGroup` | MobileAppAdGroupGet | Параметры группы для продвижения мобильных приложений. || || `DynamicTextAdGroup` | DynamicTextAdGroupGet | Параметры группы динамических объявлений, для которых источником данных является сайт. || || `DynamicTextFeedAdGroup` | DynamicTextFeedAdGroupGet | Параметры группы динамических объявлений, для которых источником данных является фид. || || `SmartAdGroup` | SmartAdGroupGet | Параметры группы смарт-баннеров. || || `TextAdGroupFeedParams` | TextAdGroupFeedParamsGet | Параметры группы текстово-графических объявлений. || || `UnifiedAdGroup` | UnifiedAdGroupGet | Параметры единой перфоманс группы. См. [Тип группы](https://yandex.ru/dev/direct/doc/dg/objects/adgroup.html#types). || || **Структура MobileAppAdGroupGet** | > | > || || `StoreUrl` | string | Ссылка на приложение в магазине приложений AppStore или Google Play (не более 1024 символов). Должна содержать протокол. Недоступна для изменения. См. раздел [Ссылка на приложение в магазине приложений](https://yandex.ru/support/direct/products-mobile-apps-ads/app-link.html) Справки Директа. {% note alert %} Во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение. Если в кампании ранее были созданы группы с разными ссылками на приложение, то при добавлении разрешено указать ссылку на приложение, которое отображается в параметрах кампании в веб-интерфейсе Директа. {% endnote %} || || `TargetDeviceType` | array of DeviceTypeEnum | На каких устройствах показывать объявления: - DEVICE_TYPE_MOBILE — смартфоны; - DEVICE_TYPE_TABLET — планшеты. || || `TargetCarrier` | CarrierEnum | По каким типам подключения к интернету показывать объявления: - WI_FI_ONLY — только по Wi-FI; - WI_FI_AND_CELLULAR — по мобильной связи и Wi-Fi. || || `TargetOperatingSystemVersion` | string | Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3. {% note info %} Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше. {% endnote %} || || `AppIconModeration` | ExtensionModeration | Результат модерации иконки мобильного приложения. || || `AppOperatingSystemType` | MobileOperatingSystemTypeEnum | Тип операционной системы (определяется автоматически на основании данных из магазина приложений): - IOS — iOS; - ANDROID — Android; - OS_TYPE_UNKNOWN — данные из магазина приложений еще не получены. || || `AppAvailabilityStatus` | AppAvailabilityStatusEnum | Доступно ли приложение в магазине приложений: - AVAILABLE — доступно; - NOT_AVAILABLE — недоступно; - UNPROCESSED — данные из магазина приложений еще не получены. || || **Структура ExtensionModeration** | > | > || || `Status` | ModerationStatusEnum | Результат модерации иконки мобильного приложения: - ACCEPTED — принята модерацией; - MODERATION — находится на модерации; - REJECTED — отклонена. || || `StatusClarification` | string | Текстовое пояснение к статусу и/или причины отклонения на модерации. || || **Структура DynamicTextAdGroupGet** | > | > || || `DomainUrl` | string | Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно. || || `DomainUrlProcessingStatus` | SourceProcessingStatusEnum | Статус генерации динамических объявлений: - UNPROCESSED — генерация объявлений не завершена; - PROCESSED — объявления созданы; - EMPTY_RESULT — не удалось создать ни одного объявления. || || `AutotargetingCategories` | array of AutotargetingCategoriesGetItem | Категории таргетинга, которые требуется добавить. || || **Структура AutotargetingCategories** | > | > || || `Category` | AutotargetingCategoriesEnum | Категория таргетинга: - EXACT — целевые запросы. Объявление точно отвечает на запросы пользователя; - ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос; - COMPETITOR — запросы с упоминанием конкурентов. Поиск продвигаемого продукта у конкурентов; - BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является предложение; - ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. || || `Value` | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. || || **Структура DynamicTextFeedAdGroupGet** | > | > || || `Source` | string | Идентификатор фида. || || `FeedId` | long | Идентификатор фида. || || `SourceType` | SourceTypeGetEnum | Тип источника данных. В настоящее время доступно только значение RETAIL_FEED. || || `SourceProcessingStatus` | SourceProcessingStatusEnum | Статус генерации динамических объявлений: - UNPROCESSED — генерация объявлений не завершена; - PROCESSED — объявления созданы; - EMPTY_RESULT — не удалось создать ни одного объявления. || || `AutotargetingCategories` | array of AutotargetingCategoriesGetItem | Категории таргетинга, которые требуется добавить. || || **Структура SmartAdGroupGet** | > | > || || `FeedId` | long | Идентификатор фида, на основе которого генерируются смарт-баннеры. || || `AdTitleSource` | string, nillable | Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически. || || `AdBodySource` | string, nillable | Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически. || || **Структура TextAdGroupFeedParamsGet** | > | > || || `FeedId` | long | Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления. || || `FeedCategoryIds` | ArrayOfLong | Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления. Если идентификаторы категорий не заданы, используются все категории из фида. || || **Структура UnifiedAdGroupGet** | > | > || || `OfferRetargeting` | YesNoEnum | Признак включения офферного ретаргетинга. || |# ## Примеры {#samples} **Пример запроса**   ```javascript translate=no { "method" : "get", "params" : { "SelectionCriteria" : { "CampaignIds" : [ 2991372, 4193065, 4193084, 7273721 ], "Statuses" : [ "DRAFT" ] }, "FieldNames" : [ "Id", "Name", "CampaignId", "Status", "RegionIds", "NegativeKeywords" ] } } ``` **Пример ответа**   ```javascript translate=no { "result" : { "AdGroups" : [ { "Id" : 45625656, "Status" : "DRAFT", "CampaignId" : 4193065, "RegionIds" : [ 225 ], "NegativeKeywords" : null, "Name" : "AdGroup #1" }, { "Id" : 198171138, "Status" : "DRAFT", "CampaignId" : 7273721, "RegionIds" : [ 225 ], "NegativeKeywords" : null, "Name" : "AdGroup #2" }, { "Id" : 636056252, "Status" : "DRAFT", "CampaignId" : 7273721, "RegionIds" : [ 0 ], "NegativeKeywords" : { "Items" : [ "куплю" ] }, "Name" : "AdGroup #3" } ] } } ```