get

Returns parameters of ads that match the specified criteria.

  1. Restrictions
  2. Request
  3. Response

Restrictions

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* AdsSelectionCriteria */
      "Ids": [(long), ... ],
      "States": [( "OFF" | ... | "ARCHIVED" ), ... ],
      "Statuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "Types": [( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD" | "CPC_VIDEO_AD" | "CPM_BANNER_AD" ), ... ],
      "Mobile": ( "YES" | "NO" ),
      "VCardIds": [(long), ... ],
      "SitelinkSetIds": [(long), ... ],
      "AdImageHashes": [(string), ... ],
      "VCardModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "SitelinksModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "AdImageModerationStatuses": [( "ACCEPTED" | ... | "REJECTED" ), ... ],
      "AdExtensionIds": [(long), ... ]
    }, /* required */
    "FieldNames": [( "AdCategories" | ... | "Subtype" ), ... ], /* required */
    "TextAdFieldNames": [( "Title" | ... | "VideoExtension" ), ... ],
    "MobileAppAdFieldNames": [( "Title" | ... | "TrackingUrl" ), ... ],
    "DynamicTextAdFieldNames": [( "Text" | ... | "AdExtensions" )],
    "TextImageAdFieldNames": [( "AdImageHash" | "Href" ), ... ],
    "MobileAppImageAdFieldNames": [( "AdImageHash" | "TrackingUrl" ), ... ],
    "TextAdBuilderAdFieldNames": [( "Creative" | "Href" ), ... ],
    "MobileAppAdBuilderAdFieldNames": [( "Creative" | "TrackingUrl" ), ... ],
    "CpcVideoAdBuilderAdFieldNames": [( "Creative" | "Href" ), ... ], 
    "CpmBannerAdBuilderAdFieldNames": [( "Creative" | "Href" | "TrackingPixels" ), ... ],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  } 
}

Parameters are described below.

ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteriaAdsSelectionCriteria

Criteria for selecting ads.

Yes
FieldNamesarray of AdFieldEnum

Names of top-level parameters to get.

Yes
TextAdFieldNamesarray of TextAdFieldEnumNames of parameters to get for a text and image ad. See Ad type.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from TextAdFieldNames are not returned.
No
MobileAppAdFieldNamesarray of MobileAppAdFieldEnumNames of parameters to get for a mobile app ad.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from MobileAppAdFieldNames are not returned.
No
DynamicTextAdFieldNamesarray of DynamicTextAdFieldEnumNames of parameters to get for a dynamic ad.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from DynamicTextAdFieldNames are not returned.
No
TextImageAdFieldNamesarray of TextImageAdFieldEnumNames of parameters to get for an image ad that was created from an image (in a group of text and image ads).
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from TextImageAdFieldNames are not returned.
No
MobileAppImageAdFieldNamesarray of MobileAppImageAdFieldEnumNames of parameters to get for an image ad that was created from an image (in a group of mobile app ads).
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from MobileAppImageAdFieldNames are not returned.
No
TextAdBuilderAdFieldNamesarray of TextAdBuilderAdFieldEnumNames of parameters to get for an image ad that was created from a creative (in a group of text and image ads).
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from TextAdBuilderAdFieldNames are not returned.
No
MobileAppAdBuilderAdFieldNamesarray of MobileAppAdBuilderAdFieldEnumNames of parameters to get for an image ad that was created from a creative (in a group of mobile app ads).
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from MobileAppAdBuilderAdFieldNames are not returned.
No
CpcVideoAdBuilderAdFieldNamesarray of CpcVideoAdBuilderAdFieldNamesThe names of video ad parameters to get. See
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from CpcVideoAdBuilderAdFieldNames are not returned.
No
CpmBannerAdBuilderAdFieldNamesarray of CpmBannerAdBuilderAdFieldEnumNames of parameters to get for a display ad. See Ad type.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from CpmBannerAdBuilderAdFieldNames are not returned.
No
PageLimitOffset

Structure that defines the page for paginated selection of data.

No
AdsSelectionCriteria structure
Idsarray of longSelects ads with the specified IDs. From 1 to 10,000 items in the array.At least one of the parameters CampaignIds, AdGroupIds, or Ids (or all may be present)
AdGroupIdsarray of longSelects ads from the specified groups. From 1 to 1000 items in the array.
CampaignIdsarray of longSelects ads from the specified campaigns. From 1 to 10 items in the array.
Statesarray of AdStateSelectionEnumSelects ads based on the specified states. See Ad status and state.No
Statusesarray of AdStatusSelectionEnumSelects ads based on the specified statuses. See Ad status and state.No
Typesarray of AdTypeEnum

Selects ads based on the specified types. See Ad type.

Note. Filtering ads by subtype is not supported. When the IMAGE_AD value is specified, image ads are returned regardless of the subtype.
No
MobileYesNoEnum

Selects ads based on whether the ad is a mobile ad:

  • YES — Mobile ads.
  • NO — Regular ads.

If the YES value is set, only text and image ads are received. Don't set this value if you need to get other types of ads.

No
VCardIdsarray of longSelects ads with the specified vCards. From 1 to 50 items in the array.

If this parameter is set, only text and image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No
SitelinkSetIdsarray of longSelects ads with the specified sets of sitelinks. From 1 to 50 items in the array.

If this parameter is set, only text and image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No
AdImageHashesarray of stringSelects ads with the specified images. From 1 to 50 items in the array.No
VCardModerationStatusesarray of ExtensionStatusSelectionEnumSelects ads based on results of vCard review. For a description of the statuses, see the section Ad extensions.

If this parameter is set, only text and image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No
SitelinksModerationStatusesarray of ExtensionStatusSelectionEnumSelects ads based on results of sitelink review: For a description of the statuses, see the section Ad extensions.

If this parameter is set, only text and image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No
AdImageModerationStatusesarray of ExtensionStatusSelectionEnumSelects ads based on results of image review. For a description of the statuses, see the section Ad extensions.

If this parameter is set, only text and image ads, dynamic ads, and ads for mobile apps will be returned. Don't set it if you need to get other types of ads.

No
AdExtensionIdsarray of longSelects ads with the specified extensions. From 1 to 50 items in the array.

If this parameter is set, only text and image ads and dynamic ads will be returned. Don't set it if you need to get other types of ads.

No

Response

Response structure in JSON format:

{
  "result": { /* result */
    "Ads": [{  /* AdGetItem */
      "Id": (long),
      "CampaignId": (long),
      "AdGroupId": (long),
      "Status": ( "ACCEPTED" | ... | "UNKNOWN" ),
      "State": ( "OFF" | ... | "UNKNOWN" ),
      "StatusClarification": (string),
      "AdCategories": {  /* ArrayOfAdCategoryEnum */
        "Items": [( "ABORTION" | ... | "TOBACCO" ), ... ] /* required */
      }, /* nillable */ 
      "AgeLabel": ( "AGE_0" | ... | "MONTHS_12"), /* nillable */
      "Type": ( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD" | "CPC_VIDEO_AD" | "CPM_BANNER_AD" ),
      "Subtype": ( "NONE" | "TEXT_IMAGE_AD" | "MOBILE_APP_IMAGE_AD" |  "TEXT_AD_BUILDER_AD" | "MOBILE_APP_AD_BUILDER_AD" ),
      "TextAd": {  /* TextAdGet */
        "Title": (string),
        "Title2": (string), /* nillable */ 
        "Text": (string),
        "Href": (string), /* nillable */ 
        "Mobile": ( "YES" | "NO" ),
        "DisplayDomain": (string), /* nillable */ 
        "DisplayUrlPath": (string), /* nillable */ 
        "VCardId": (long), /* nillable */ 
        "AdImageHash": (string), /* nillable */ 
        "SitelinkSetId": (long), /* nillable */
        "DisplayUrlPathModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */ 
        "VCardModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */ 
        "SitelinksModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */ 
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string)
        }, /* nillable */ 
        "AdExtensions": [{  /* AdExtensionAdGetItem */
          "AdExtensionId": (long), /* required */
          "Type": ( "CALLOUT" | "UNKNOWN" ) /* required */
        }, ... ],
        "VideoExtension": {  /* VideoExtensionGetItem */
          "CreativeId": (long), /* required */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ),
          "ThumbnailUrl": (string), /* required */
          "PreviewUrl": (string) /* required */
        } /* nillable */
      },
      "MobileAppAd": {  /* MobileAppAdGet */
        "Title": (string),
        "Text": (string),
        "TrackingUrl": (string), /* nillable */ 
        "Features": [{  /* MobileAppAdFeatureGetItem */
          "Feature": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */
          "Enabled": ( "YES" | "NO" ), /* required */
          "IsAvailable": ( "YES" | "NO" | "UNKNOWN" ) /* required */
        }, ... ],
        "Action": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ),
        "AdImageHash": (string), /* nillable */ 
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string),
        } /* nillable */ 
      }, 
      "DynamicTextAd": {  /* DynamicTextAdGet */
        "Text": (string),             
        "VCardId": (long), /* nillable */ 
        "AdImageHash": (string), /* nillable */ 
        "SitelinkSetId": (long), /* nillable */ 
        "VCardModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string),
        }, /* nillable */ 
        "SitelinksModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string), 
        } /* nillable */ 
        "AdImageModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | ... | "UNKNOWN" ), /* required */
          "StatusClarification": (string),
        }, /* nillable */ 
        "AdExtensions": [{  /* AdExtensionAdGetItem */
          "AdExtensionId": (long), /* required */
          "Type": ( "CALLOUT" | "UNKNOWN" ) /* required */
        }, ... ]
      },
      "TextImageAd": {  /* TextImageAdGet */
        "Href": (string),
        "AdImageHash": (string)
      },
      "MobileAppImageAd": {  /* MobileAppImageAdGet */
        "TrackingUrl": (string), /* nillable */
        "AdImageHash": (string)
      },
      "TextAdBuilderAd": {  /* TextAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        }, 
        "Href": (string)
      },
      "MobileAppAdBuilderAd": {  /* MobileAppAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        }, 
        "TrackingUrl": (string) /* nillable */
      },
      "CpcVideoAdBuilderAd": {  /* CpcVideoAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        }, 
        "Href": (string)
      },
      "CpmBannerAdBuilderAd": {  /* CpmBannerAdBuilderAdGet */
        "Creative": { /* AdBuilderAdGetItem */
          "CreativeId": (long), /* required */
          "ThumbnailUrl": (string),
          "PreviewUrl": (string)
        },
        "Href": (string),
        "TrackingPixels": { /* TrackingPixelGetItem */ 
          "TrackingPixel": (string), /* required */
          "Provider": (string) /* required */
        }
      }
    }, ... ],
    "LimitedBy": (long)
  }
}

Parameters are described below.

ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
Adsarray of AdGetItemAds.
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.
AdGetItem structure
IdlongThe ad ID.
CampaignIdlongID of the campaign that the ad belongs to.
AdGroupIdlongID of the group that the ad belongs to.
StatusStatusEnumStatus of the ad. For a description of the statuses, see the section Status and state of an ad.
StatusClarificationstring

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

StateStateEnumState of the ad. For a description of the states, see the section Status and state of an ad.
AdCategoriesArrayOfString, nillableSpecial category.
AgeLabelAgeLabelEnum, nillableAge label.
TypeAdTypeEnumType of ad. See Ad type.
SubtypeAdSubtypeEnumThe ad subtype. For ads with a type other than IMAGE_AD, the value NONE is returned.
TextAdTextAdGetParameters of a text and image ad.
MobileAppAdMobileAppAdGetParameters of a mobile app ad.
DynamicTextAdDynamicTextAdGetParameters of a dynamic ad.
TextImageAdTextImageAdGetParameters of an image ad that was created from an image (in a group of text and image ads).
MobileAppImageAdMobileAppImageAdGetParameters of an image ad that was created from an image (in a group of mobile app ads).
TextAdBuilderAdTextAdBuilderAdGetParameters of an image ad that was created from a creative (in a group of text and image ads).
MobileAppAdBuilderAdMobileAppAdBuilderAdGetParameters of an image ad that was created from a creative (in a group of mobile app ads).
CpcVideoAdBuilderAdCpcVideoAdBuilderAdGetVideo ad parameters.
CpmBannerAdBuilderAdCpmBannerAdBuilderAdGetDisplay ad parameters.
TextAdGet structure
Titlestring

Title 1.

Maximum of 35 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

Title2string, nillable

Title 2.

Maximum of 30 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

Textstring

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

Hrefstring, nillable

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

MobileYesNoEnumIndicates whether this is a mobile ad: YES or NO. See Mobile ads in the Help for Yandex.Direct.
DisplayDomainstring, nillableDomain being advertised. Detected automatically from the ad link.
DisplayUrlPathstring, nillable

Display link. Allowed only with the Href parameter. Maximum of 20 characters. If using a template, the # character isn't counted in the length.

It may contain letters, numbers, and the symbols -, №, /, %, #. Spaces, underscores (_), and the double characters -- and // are not allowed.

See Display link in the Help for Yandex.Direct.

VCardIdlong, nillableID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetIdlong, nillableID of a set of sitelinks. Allowed only with the Href parameter.
AdImageHashstring, nillable

Hash of the image.

For text and image ads, only images with the REGULAR or WIDE type are acceptable. See Image type.
DisplayUrlPathModerationExtensionModeration, nillableResult of reviewing the display link.
VCardModerationExtensionModeration, nillableResult of vCard review.
SitelinksModerationExtensionModeration, nillableResult of reviewing the set of sitelinks.
AdImageModerationExtensionModeration, nillableResult of image review.
AdExtensionsarray of AdExtensionAdGetItemExtensions.
VideoExtensionVideoExtensionGetItem, nillable

Video extension.

See the section Video extensions in the Help for Yandex.Direct.

ExtensionModeration structure
StatusStatusEnumResult of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Ad extensions.
StatusClarificationstringText explanation of the status and/or reasons for rejection after review.
AdExtensionAdGetItem structure
AdExtensionIdlongExtension ID.
TypeAdExtensionTypeEnumExtension type. Only one type of extension is available at this time — the “Callout” (CALLOUT).
VideoExtensionGetItem structure
CreativeIdlongID of the creative.
StatusStatusEnumResult of reviewing the video extension assignment to the ad. For a description of the statuses, see the section Ad extensions.
ThumbnailUrlstringURL for the preview image.
PreviewUrlstringURL for the preview video.
MobileAppAdGet structure
Titlestring

Header.

Maximum of 33 characters, counting “narrow” characters. Maximum of 22 characters per word. If using a template, the # character isn't counted in the length.

Textstring

Ad text.

Maximum of 75 characters, counting “narrow” characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

Featuresarray of MobileAppAdFeatureGetItemAdd-ons that need to be automatically downloaded from the app store and displayed in the ad.
TrackingUrlstring, nillableTracking link for tracking app installations.
ActionMobileAppAdActionEnum

The button label:

  • DOWNLOAD — “Download”

  • GET — “Get”

  • INSTALL — “Install”

  • MORE — “More”

  • OPEN — “Open”

  • UPDATE — “Update”

  • PLAY — “Play”

  • BUY_AUTODETECT — The label depends on the application price: “Buy” if the price is something other than zero, or “Free” if the price is set to zero.

AdImageHashstring, nillable

Hash of the image.

For mobile app ads, only images with the WIDE type are acceptable. See Image type.

AdImageModerationExtensionModeration, nillableResult of image review.
MobileAppAdFeatureGetItem structure
FeatureMobileAppFeatureEnum

Type of extension:

  • PRICE — price
  • ICON — icon
  • CUSTOMER_RATING — rating
  • RATINGS — number of ratings (shown only if the rating is displayed)
Note. Returns data about add-ons that were specified when creating or editing the ad, as well as add-ons that were downloaded from the app store.
EnabledYesNoEnum

Whether to display an add-on in the ad.

Note.
  • If the add-on couldn't be downloaded from the app store, the YES value is available, but this add-on is not shown when displaying the ad.
  • The number of ratings is only shown together with the average rating: if NO is set for the CUSTOMER_RATING type, but YES is set for RATINGS, the number of ratings is not displayed.
IsAvailableYesNoUnknownEnum

Whether the add-on was successfully downloaded from the app store:

  • YES — Add-on was downloaded.
  • NO — Add-on couldn't be downloaded.
  • UNKNOWN — Downloading the add-on hasn't been attempted yet.
DynamicTextAdGet structure
Textstring

Ad text.

Maximum of 81 characters not counting "narrow" characters, plus up to 15 "narrow" characters. Maximum of 23 characters per word. If using a template, the # character isn't counted in the length.

VCardIdlong, nillableID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetIdlong, nillableID of a set of sitelinks.
AdImageHashstring, nillable

Hash of the image.

For dynamic ads, only images with the REGULAR or WIDE type are acceptable. See Image type.

VCardModerationExtensionModeration, nillableResult of vCard review.
SitelinksModerationExtensionModeration, nillableResult of reviewing the set of sitelinks.
AdImageModerationExtensionModeration, nillableResult of image review.
AdExtensionsarray of AdExtensionAdGetItemExtensions.
TextImageAdGet structure
Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

AdImageHashstring

Hash of the image.

For image ads, only images with the FIXED_IMAGE type are acceptable. See Image type.

MobileAppImageAdGet structure
TrackingUrlstring, nillableTracking link for tracking app installations.
AdImageHashstring

Hash of the image.

For image ads, only images with the FIXED_IMAGE type are acceptable. See Image type.

TextAdBuilderAdGet structure
CreativeAdBuilderAdGetItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for image ads in the Help for Yandex.Direct.

Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

MobileAppAdBuilderAdGet structure
CreativeAdBuilderAdGetItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for image ads in the Help for Yandex.Direct.

TrackingUrlstring, nillableTracking link for tracking app installations.
CpcVideoAdBuilderAdGet structure
CreativeAdBuilderAdGetItem

A creative that was created in the Ad Builder.

See the section Creative Ad Builder for video extensions in the Help for Yandex.Direct.

Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

CpmBannerAdBuilderAdGet structure
CreativeAdBuilderAdGetItem

A creative that was uploaded in the web interface or created in the Ad Builder.

See Create a display campaign in the Help for Yandex.Direct.

Hrefstring

Link to the advertiser's website. Maximum of 1024 characters. If using a template, the # character isn't counted in the length.

It must include the protocol and domain name. May contain substitution variables.

TrackingPixelsarray of TrackingPixelGetItemA Yandex.Audience pixel and/or an ADFOX, TNS, or Gemius impression tag.
AdBuilderAdGetItem structure
CreativeIdlongID of the creative.
ThumbnailUrlstringURL for the preview thumbnail.
PreviewUrlstringURL for the preview image.
TrackingPixelGetItem structure
TrackingPixelstringLink to a Yandex.Audience pixel or an ADFOX, TNS, or Gemius impression tag.
ProviderstringProvider of the pixel or impression tag.