get

Returns parameters of groups that match the specified criteria.

  1. Restrictions
  2. Request
  3. Response
  4. Examples

Restrictions

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "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" ), ... ],
      "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), ... ],
      "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ],
      "AppIconStatuses": [( "ACCEPTED" | "MODERATION" | "REJECTED" ), ... ]
    }, /* required */
    "FieldNames": [( "CampaignId" | ... | "Type" ), ... ], /* required */
    "MobileAppAdGroupFieldNames": [( "StoreUrl" | ... | "AppIconModeration" ), ... ],
    "DynamicTextAdGroupFieldNames": [( "DomainUrl" | "DomainUrlProcessingStatus" ), ... ],
    "DynamicTextFeedAdGroupFieldNames": [( "Source" | "SourceType" | "SourceProcessingStatus" )],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteriaAdGroupsSelectionCriteriaGroup selection criteria.Yes
FieldNamesarray of AdGroupFieldEnumNames of top-level parameters to get.Yes
MobileAppAdGroupFieldNamesarray of MobileAppAdGroupFieldEnumNames of parameters to get for a mobile app ad group. See Group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from MobileAppAdGroupFieldNames are not returned.
No
DynamicTextAdGroupFieldNamesarray of DynamicTextAdGroupFieldEnumNames of parameters for a group of dynamic ads that has a website as the data source. See Group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextAdGroupFieldNames are not returned.
No
DynamicTextFeedAdGroupFieldNamesarray of DynamicTextFeedAdGroupFieldEnumNames of parameters for a group of dynamic ads that has a feed as the data source. See Group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextFeedAdGroupFieldNames are not returned.
No
PageLimitOffsetStructure that defines the page for paginated selection of data.No
AdGroupsSelectionCriteria structure
CampaignIdsarray of longSelects groups of the specified campaigns. From 1 to 10 items in the array.At least one of the CampaignIds or Ids parameters, or both
Idsarray of longSelects groups with the specified IDs. From 1 to 10,000 items in the array.
Typesarray of AdGroupTypesEnumSelects groups of the specified types. See Group type.No
Statusesarray of AdGroupStatusSelectionEnumSelects groups with the specified statuses. See Group Status.No
ServingStatusesarray of ServingStatusEnumSelects groups with the specified ad serving statuses. See Serving status for the ad group.No
AppIconStatusesarray of AdGroupAppIconStatusSelectionEnumSelects groups based on results of app icon review:
  • ACCEPTED — Accepted after review.

  • MODERATION — Currently under review.

  • REJECTED — Rejected.

If this parameter is set, only groups for mobile app advertising will be received. Don't set it if you need to get other types of groups.

No
Note.
  • If the SelectionCriteria structure has more than one criterion set, you will get the groups that simultaneously match all the criteria.

Response

Response structure in JSON format:

{
  "result": { /* result */
    "AdGroups": [{  /* AdGroupGetItem */
      "Id": (long),
      "Name": (string),
      "CampaignId": (long),
      "RegionIds": [(long), ... ],
      "RestrictedRegionIds": {  /* ArrayOfLong */
        "Items": [(long), ... ] /* required */
      }, /* nillable */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* 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" ),
      "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" )
      },
      "DynamicTextFeedAdGroup": {  /* DynamicTextFeedAdGroupGet */
        "Source": (string),
        "SourceType": ( "RETAIL_FEED" | "UNKNOWN" ),
        "SourceProcessingStatus": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" )
      }
    }, ... ],
  "LimitedBy": (long)
  }
}
ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
AdGroupsarray of AdGroupGetItemGroups of ads.
LimitedBylongSequential number of the last object returned. It is included if there was a limit on the number of objects in the response. See the section Paginated data selection.
AdGroupGetItem structure
IdlongID of the ad group.
NamestringName of the group.
CampaignIdlongThe campaign ID.
RegionIdsarray of long

IDs of regions where ad impressions are enabled or disabled.

The ID 0 specifies to display ads in all regions.

A minus sign before a region ID disables impressions in this region. For example, [1,-219] indicates to display for Moscow and the entire Moscow area, except Chernogolovka.

RestrictedRegionIdsArrayOfLong, nillableIDs of regions where ads won't be served due to legal restrictions.
NegativeKeywordsArrayOfString, nillable

Negative keywords that are shared by all the ad group's keywords.

TrackingParamsstring

GET parameters for tracking traffic sources that are added to the link of all ads in the group (maximum of 1024 characters). May contain substitution variables.

For example: from=direct&ad={ad_id}

The parameter can be specified for any type of group, but it is currently only used for groups of dynamic ads. For other types of groups, the specified GET parameters aren't added to links.

StatusStatusEnumGroup status. See Group Status.
ServingStatusServingStatusEnumServing status for the ad group. See Serving status for the ad group.
TypeAdGroupTypesEnumType of ad group. See Group type.
SubtypeAdGroupSubtypeEnumThe subtype of ad group. For a group with a type other than DYNAMIC_TEXT_AD_GROUP or CPM_BANNER_AD_GROUP, the value NONE is returned.
MobileAppAdGroupMobileAppAdGroupGetParameters of groups for mobile app advertising. See Group type.
DynamicTextAdGroupDynamicTextAdGroupGetParameters for a group of dynamic ads that has a website as the data source. See Group type.
DynamicTextFeedAdGroupDynamicTextFeedAdGroupGetParameters for a group of dynamic ads that has a feed as the data source. See Group type.
MobileAppAdGroupGet structure
StoreUrlstring

Link to the app in AppStore or Google Play (maximum of 1024 characters). The link must contain the protocol. Not editable.

See Link to App in Store in the Help for Yandex.Direct.

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

If groups with different app links were previously created in the campaign, then you are allowed to specify the app link that is shown in your campaign settings in the Yandex.Direct web interface.

TargetDeviceTypearray of DeviceTypeEnumWhich devices to show ads on:
  • DEVICE_TYPE_MOBILE — smartphones

  • DEVICE_TYPE_TABLET — tablets

TargetCarrierCarrierEnumWhich types of internet connections to show ads on:
  • WI_FI_ONLY — only Wi-Fi
  • WI_FI_AND_CELLULAR — cellular internet and Wi-Fi
TargetOperatingSystemVersionstringThe minimum OS version to display the ad on. For example, 2.3.
Note. If the minimum OS version in the app store is higher than the one set in this parameter, ads are displayed only for OS versions equal to or higher than the one in the app store.
AppIconModerationExtensionModerationResult of reviewing the mobile app icon.
AppOperatingSystemTypeMobileOperatingSystemTypeEnum

Type of operating system (detected automatically based data from the app store):

  • IOS — iOS
  • ANDROID — Android
  • OS_TYPE_UNKNOWN — Data hasn't been received from the app store yet.
AppAvailabilityStatusAppAvailabilityStatusEnum

Whether the app is available in the app store:

  • AVAILABLE — The app is available.

  • NOT_AVAILABLE — The app isn't available.

  • UNPROCESSED — Data hasn't been received from the app store yet.

ExtensionModeration structure
StatusModerationStatusEnumResult of reviewing the mobile app icon:
  • ACCEPTED — Accepted after review.

  • MODERATION — Currently under review.

  • REJECTED — Rejected.

StatusClarificationstringText explanation of the status and/or reasons for rejection after review.
DynamicTextAdGroupGet structure
DomainUrlstringThe domain name of the site to generate dynamic ads for (a maximum of 100 characters). The protocol can be omitted.
DomainUrlProcessingStatusSourceProcessingStatusEnum

Status of generating dynamic ads:

  • UNPROCESSED — Ad generation has not finished.

  • PROCESSED — Ads have been created.

  • EMPTY_RESULT — No ads could be created.

DynamicTextFeedAdGroupGet structure
SourcestringThe feed ID.
SourceTypeSourceTypeGetEnumThe type of data source. Only the value RETAIL_FEED is currently available.
SourceProcessingStatusSourceProcessingStatusEnum

Status of generating dynamic ads:

  • UNPROCESSED — Ad generation has not finished.

  • PROCESSED — Ads have been created.

  • EMPTY_RESULT — No ads could be created.

Examples

Request example
{
  "method" : "get",
  "params" : {
    "SelectionCriteria" : {
      "CampaignIds" : [
        2991372,
        4193065,
        4193084,
        7273721
      ],
      "Statuses" : [ "DRAFT" ]
    },
    "FieldNames" : [
      "Id",
      "Name",
      "CampaignId",
      "Status",
      "RegionIds",
      "NegativeKeywords"
    ]
  }
}
Response example
{
  "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" : [
            "buy"
          ]
        },
        "Name" : "AdGroup #3"
      }
    ]
  }
}