Documentation

get

Returns parameters of groups that match the specified criteria.

Restrictions

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { 
    "SelectionCriteria
[no-highlight[

Group selection criteria.

Required

Yes

]no-highlight]
": { /* AdGroupsSelectionCriteria */ "CampaignIds
[no-highlight[

Selects groups of the specified campaigns. From 1 to 10 items in the array.

Required

At least one of the CampaignIds or Ids parameters, or both

]no-highlight]
": [(long), ... ], "Ids
[no-highlight[

Selects groups with the specified IDs. From 1 to 10,000 items in the array.

Required

At least one of the CampaignIds or Ids parameters, or both

]no-highlight]
": [(long), ... ], "Types
[no-highlight[

Selects groups of the specified types. See Ad group type.

Required

No

]no-highlight]
": [( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" ), ... ], "Statuses
[no-highlight[

Selects groups with the specified statuses. See Ad group status.

Required

No

]no-highlight]
": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), ... ], "ServingStatuses
[no-highlight[

Selects groups with the specified ad serving statuses. See Ad group serving status.

Required

No

]no-highlight]
": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ], "AppIconStatuses
[no-highlight[

Selects 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.

Required

No

]no-highlight]
": [( "ACCEPTED" | "MODERATION" | "REJECTED" ), ... ] }, /* required */ "FieldNames
[no-highlight[

Names of top-level parameters to get.

Required

Yes

]no-highlight]
": [( "CampaignId" | ...
[no-highlight[

“CampaignId“ | “Id“ | “Name“ | “NegativeKeywords“ | “RegionIds“ | “RestrictedRegionIds“ | “ServingStatus“ | “Status“ | “Subtype“ | “TrackingParams“ | “Type“

]no-highlight]
| "Type" ), ... ], /* required */ "MobileAppAdGroupFieldNames
[no-highlight[

Names of parameters to get for a mobile app ad group. See Ad group type.

Note. If a different type of group is selected according to SelectionCriteria, parameters from MobileAppAdGroupFieldNames are not returned.

Required

No

]no-highlight]
": [( "StoreUrl" | ...
[no-highlight[“StoreUrl“ | “TargetDeviceType“ | “TargetCarrier“ | “TargetOperatingSystemVersion“ | “AppIconModeration“ | “AppAvailabilityStatus“ | “AppOperatingSystemType“]no-highlight]
| "AppIconModeration" ), ... ], "DynamicTextAdGroupFieldNames
[no-highlight[

Names of parameters for a group of dynamic ads that has a website as the data source. See Ad group type.

Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextAdGroupFieldNames are not returned.

Required

No

]no-highlight]
": [( "DomainUrl" | "DomainUrlProcessingStatus" ), ... ], "DynamicTextFeedAdGroupFieldNames
[no-highlight[

Names of parameters for a group of dynamic ads that has a feed as the data source. See Ad group type.

Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextFeedAdGroupFieldNames are not returned.

Required

No

]no-highlight]
": [( "Source" | "SourceType" | "SourceProcessingStatus" )], "Page
[no-highlight[

Structure that defines the page for paginated selection of data.

Required

No

]no-highlight]
": { /* LimitOffset */ "Limit": (long), "Offset": (long) } } }
Parameter Type Description Required
params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteria AdGroupsSelectionCriteria Group selection criteria.Yes
FieldNames array of AdGroupFieldEnumNames of top-level parameters to get.Yes
MobileAppAdGroupFieldNames array of MobileAppAdGroupFieldEnumNames of parameters to get for a mobile app ad group. See Ad group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from MobileAppAdGroupFieldNames are not returned.
No
DynamicTextAdGroupFieldNames array of DynamicTextAdGroupFieldEnumNames of parameters for a group of dynamic ads that has a website as the data source. See Ad group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextAdGroupFieldNames are not returned.
No
DynamicTextFeedAdGroupFieldNames array of DynamicTextFeedAdGroupFieldEnumNames of parameters for a group of dynamic ads that has a feed as the data source. See Ad group type.
Note. If a different type of group is selected according to SelectionCriteria, parameters from DynamicTextFeedAdGroupFieldNames are not returned.
No
Page LimitOffset Structure that defines the page for paginated selection of data.No
AdGroupsSelectionCriteria structure
CampaignIds array 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
Ids array of longSelects groups with the specified IDs. From 1 to 10,000 items in the array.
Types array of AdGroupTypesEnumSelects groups of the specified types. See Ad group type.No
Statuses array of AdGroupStatusSelectionEnumSelects groups with the specified statuses. See Ad group status.No
ServingStatuses array of ServingStatusEnumSelects groups with the specified ad serving statuses. See Ad group serving status.No
AppIconStatuses array 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": { 
    "AdGroups
[no-highlight[

Groups of ads.

]no-highlight]
": [{ /* AdGroupGetItem */ "Id
[no-highlight[

ID of the ad group.

]no-highlight]
": (long), "Name
[no-highlight[

Name of the group.

]no-highlight]
": (string), "CampaignId
[no-highlight[

The campaign ID.

]no-highlight]
": (long), "RegionIds
[no-highlight[

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.

]no-highlight]
": [(long), ... ], "RestrictedRegionIds
[no-highlight[

IDs of regions where ads won‘t be served due to legal restrictions.

]no-highlight]
": { /* ArrayOfLong */ "Items": [(long), ... ] /* required */ }, /* nillable */ "NegativeKeywords
[no-highlight[

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

]no-highlight]
": { /* ArrayOfString */ "Items": [(string), ... ] /* required */ }, /* nillable */ "TrackingParams
[no-highlight[

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.

]no-highlight]
": (string), "Status
[no-highlight[

Group status. See Ad group status.

]no-highlight]
": ( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), "ServingStatus
[no-highlight[

Serving status for the ad group. See Ad group serving status.

]no-highlight]
": ( "ELIGIBLE" | "RARELY_SERVED" ), "Type
[no-highlight[

Type of ad group. See Ad group type.

]no-highlight]
": ( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" ), "Subtype
[no-highlight[

The subtype of ad group. For a group with a type other than DYNAMIC_TEXT_AD_GROUP, the value NONE is returned.

]no-highlight]
": ( "WEBPAGE" | "FEED" | "NONE" ), "MobileAppAdGroup
[no-highlight[

Parameters of groups for mobile app advertising. See Ad group type.

]no-highlight]
": { /* MobileAppAdGroupGet */ "StoreUrl
[no-highlight[

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.

]no-highlight]
": (string), "TargetDeviceType
[no-highlight[

Which devices to show ads on:

  • DEVICE_TYPE_MOBILE — smartphones

  • DEVICE_TYPE_TABLET — tablets

]no-highlight]
": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ], "TargetCarrier
[no-highlight[

Which types of internet connections to show ads on:

  • WI_FI_ONLY — only Wi-Fi
  • WI_FI_AND_CELLULAR — cellular internet and Wi-Fi

]no-highlight]
": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ), "TargetOperatingSystemVersion
[no-highlight[

The 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.

]no-highlight]
": (string), "AppIconModeration
[no-highlight[

Result of reviewing the mobile app icon.

]no-highlight]
": { /* ExtensionModeration */ "Status
[no-highlight[

Result of reviewing the mobile app icon:

  • ACCEPTED — Accepted after review.

  • MODERATION — Currently under review.

  • REJECTED — Rejected.

]no-highlight]
": ( "ACCEPTED" | "MODERATION" | "REJECTED" ), /* required */ "StatusClarification
[no-highlight[

Text explanation of the status and/or reasons for rejection after review.

]no-highlight]
": (string) } /* nillable */ "AppOperatingSystemType
[no-highlight[

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.
]no-highlight]
": ("IOS" | "ANDROID" | "OS_TYPE_UNKNOWN"), "AppAvailabilityStatus
[no-highlight[

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.

]no-highlight]
": ("UNPROCESSED" | "AVAILABLE" | "NOT_AVAILABLE") }, "DynamicTextAdGroup
[no-highlight[

Parameters for a group of dynamic ads that has a website as the data source. See Ad group type.

]no-highlight]
": { /* DynamicTextAdGroupGet */ "DomainUrl
[no-highlight[

The domain name of the site to generate dynamic ads for (a maximum of 100 characters). The protocol can be omitted.

]no-highlight]
": (string), "DomainUrlProcessingStatus
[no-highlight[

Status of generating dynamic ads:

  • UNPROCESSED — Ad generation has not finished.

  • PROCESSED — Ads have been created.

  • EMPTY_RESULT — No ads could be created.

]no-highlight]
": ("EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" ) }, "DynamicTextFeedAdGroup
[no-highlight[

Parameters for a group of dynamic ads that has a feed as the data source. See Ad group type.

]no-highlight]
": { /* DynamicTextFeedAdGroupGet */ "Source
[no-highlight[

The feed ID.

]no-highlight]
": (string), "SourceType
[no-highlight[

The type of data source. Only the value RETAIL_FEED is currently available.

]no-highlight]
": ( "RETAIL_FEED" | "UNKNOWN" ), "SourceProcessingStatus
[no-highlight[

Status of generating dynamic ads:

  • UNPROCESSED — Ad generation has not finished.

  • PROCESSED — Ads have been created.

  • EMPTY_RESULT — No ads could be created.

]no-highlight]
": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" ) } }, ... ], "LimitedBy
[no-highlight[

Sequential 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 selection.

]no-highlight]
": (long) } }
Parameter Type Description
result structure (for JSON) / GetResponse (for SOAP)
AdGroups array of AdGroupGetItemGroups of ads.
LimitedBy longSequential 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 selection.
AdGroupGetItem structure
Id longID of the ad group.
Name stringName of the group.
CampaignId longThe campaign ID.
RegionIds array 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.

RestrictedRegionIds ArrayOfLong
[no-highlight[

Object containing the Items numeric array

]no-highlight]
, nillable
IDs of regions where ads won't be served due to legal restrictions.
NegativeKeywords ArrayOfString
[no-highlight[

Object containing an array of Items strings

]no-highlight]
, nillable

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

TrackingParams string

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.

Status StatusEnumGroup status. See Ad group status.
ServingStatus ServingStatusEnumServing status for the ad group. See Ad group serving status.
Type AdGroupTypesEnumType of ad group. See Ad group type.
Subtype AdGroupSubtypeEnumThe subtype of ad group. For a group with a type other than DYNAMIC_TEXT_AD_GROUP, the value NONE is returned.
MobileAppAdGroup MobileAppAdGroupGet Parameters of groups for mobile app advertising. See Ad group type.
DynamicTextAdGroup DynamicTextAdGroupGet Parameters for a group of dynamic ads that has a website as the data source. See Ad group type.
DynamicTextFeedAdGroup DynamicTextFeedAdGroupGet Parameters for a group of dynamic ads that has a feed as the data source. See Ad group type.
MobileAppAdGroupGet structure
StoreUrl string

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.

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

  • DEVICE_TYPE_TABLET — tablets

TargetCarrier CarrierEnumWhich types of internet connections to show ads on:
  • WI_FI_ONLY — only Wi-Fi
  • WI_FI_AND_CELLULAR — cellular internet and Wi-Fi
TargetOperatingSystemVersion stringThe 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.
AppIconModeration ExtensionModeration Result of reviewing the mobile app icon.
AppOperatingSystemType MobileOperatingSystemTypeEnum

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.
AppAvailabilityStatus AppAvailabilityStatusEnum

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
Status ModerationStatusEnumResult of reviewing the mobile app icon:
  • ACCEPTED — Accepted after review.

  • MODERATION — Currently under review.

  • REJECTED — Rejected.

StatusClarification stringText explanation of the status and/or reasons for rejection after review.
DynamicTextAdGroupGet structure
DomainUrl stringThe domain name of the site to generate dynamic ads for (a maximum of 100 characters). The protocol can be omitted.
DomainUrlProcessingStatus SourceProcessingStatusEnum

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
Source stringThe feed ID.
SourceType SourceTypeGetEnumThe type of data source. Only the value RETAIL_FEED is currently available.
SourceProcessingStatus SourceProcessingStatusEnum

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"
      }
    ]
  }
}