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.

Parameter Type Description Required
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteria AdsSelectionCriteria

Criteria for selecting ads.

Yes
FieldNames array of AdFieldEnum

Names of top-level parameters to get.

Yes
TextAdFieldNames array of TextAdFieldEnum Names 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
MobileAppAdFieldNames array of MobileAppAdFieldEnum Names 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
DynamicTextAdFieldNames array of DynamicTextAdFieldEnum Names 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
TextImageAdFieldNames array of TextImageAdFieldEnum Names 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
MobileAppImageAdFieldNames array of MobileAppImageAdFieldEnum Names 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
TextAdBuilderAdFieldNames array of TextAdBuilderAdFieldEnum Names 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
MobileAppAdBuilderAdFieldNames array of MobileAppAdBuilderAdFieldEnum Names 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
CpcVideoAdBuilderAdFieldNames array of CpcVideoAdBuilderAdFieldNames The 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
CpmBannerAdBuilderAdFieldNames array of CpmBannerAdBuilderAdFieldEnum Names 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
Page LimitOffset

Structure that defines the page for paginated selection of data.

No
AdsSelectionCriteria structure
Ids array of long Selects 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)
AdGroupIds array of long Selects ads from the specified groups. From 1 to 1000 items in the array.
CampaignIds array of long Selects ads from the specified campaigns. From 1 to 10 items in the array.
States array of AdStateSelectionEnum Selects ads based on the specified states. See Ad status and state. No
Statuses array of AdStatusSelectionEnum Selects ads based on the specified statuses. See Ad status and state. No
Types array 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
Mobile YesNoEnum

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
VCardIds array of long Selects 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
SitelinkSetIds array of long Selects 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
AdImageHashes array of string Selects ads with the specified images. From 1 to 50 items in the array. No
VCardModerationStatuses array of ExtensionStatusSelectionEnum Selects 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
SitelinksModerationStatuses array of ExtensionStatusSelectionEnum Selects 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
AdImageModerationStatuses array of ExtensionStatusSelectionEnum Selects 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
AdExtensionIds array of long Selects 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.

Parameter Type Description
Result structure (for JSON) / GetResponse (for SOAP)
Ads array of AdGetItem Ads.
LimitedBy long 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 data selection.
AdGetItem structure
Id long The ad ID.
CampaignId long ID of the campaign that the ad belongs to.
AdGroupId long ID of the group that the ad belongs to.
Status StatusEnum Status of the ad. For a description of the statuses, see the section Status and state of an ad.
StatusClarification string

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

State StateEnum State of the ad. For a description of the states, see the section Status and state of an ad.
AdCategories ArrayOfString, nillable Special category.
AgeLabel AgeLabelEnum, nillable Age label.
Type AdTypeEnum Type of ad. See Ad type.
Subtype AdSubtypeEnum The ad subtype. For ads with a type other than IMAGE_AD, the value NONE is returned.
TextAd TextAdGet Parameters of a text and image ad.
MobileAppAd MobileAppAdGet Parameters of a mobile app ad.
DynamicTextAd DynamicTextAdGet Parameters of a dynamic ad.
TextImageAd TextImageAdGet Parameters of an image ad that was created from an image (in a group of text and image ads).
MobileAppImageAd MobileAppImageAdGet Parameters of an image ad that was created from an image (in a group of mobile app ads).
TextAdBuilderAd TextAdBuilderAdGet Parameters of an image ad that was created from a creative (in a group of text and image ads).
MobileAppAdBuilderAd MobileAppAdBuilderAdGet Parameters of an image ad that was created from a creative (in a group of mobile app ads).
CpcVideoAdBuilderAd CpcVideoAdBuilderAdGet Video ad parameters.
CpmBannerAdBuilderAd CpmBannerAdBuilderAdGet Display ad parameters.
TextAdGet structure
Title string

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.

Title2 string, 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.

Text string

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.

Href string, 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.

Mobile YesNoEnum Indicates whether this is a mobile ad: YES or NO. See Mobile ads in the Help for Yandex.Direct.
DisplayDomain string, nillable Domain being advertised. Detected automatically from the ad link.
DisplayUrlPath string, 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.

VCardId long, nillable ID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetId long, nillable ID of a set of sitelinks. Allowed only with the Href parameter.
AdImageHash string, nillable

Hash of the image.

For text and image ads, only images with the REGULAR or WIDE type are acceptable. See Image type.
DisplayUrlPathModeration ExtensionModeration, nillable Result of reviewing the display link.
VCardModeration ExtensionModeration, nillable Result of vCard review.
SitelinksModeration ExtensionModeration, nillable Result of reviewing the set of sitelinks.
AdImageModeration ExtensionModeration, nillable Result of image review.
AdExtensions array of AdExtensionAdGetItem Extensions.
VideoExtension VideoExtensionGetItem, nillable

Video extension.

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

ExtensionModeration structure
Status StatusEnum Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Ad extensions.
StatusClarification string Text explanation of the status and/or reasons for rejection after review.
AdExtensionAdGetItem structure
AdExtensionId long Extension ID.
Type AdExtensionTypeEnum Extension type. Only one type of extension is available at this time — the “Callout” (CALLOUT).
VideoExtensionGetItem structure
CreativeId long ID of the creative.
Status StatusEnum Result of reviewing the video extension assignment to the ad. For a description of the statuses, see the section Ad extensions.
ThumbnailUrl string URL for the preview image.
PreviewUrl string URL for the preview video.
MobileAppAdGet structure
Title string

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.

Text string

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.

Features array of MobileAppAdFeatureGetItem Add-ons that need to be automatically downloaded from the app store and displayed in the ad.
TrackingUrl string, nillable Tracking link for tracking app installations.
Action MobileAppAdActionEnum

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.

AdImageHash string, nillable

Hash of the image.

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

AdImageModeration ExtensionModeration, nillable Result of image review.
MobileAppAdFeatureGetItem structure
Feature MobileAppFeatureEnum

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.
Enabled YesNoEnum

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.
IsAvailable YesNoUnknownEnum

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
Text string

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.

VCardId long, nillable ID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetId long, nillable ID of a set of sitelinks.
AdImageHash string, nillable

Hash of the image.

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

VCardModeration ExtensionModeration, nillable Result of vCard review.
SitelinksModeration ExtensionModeration, nillable Result of reviewing the set of sitelinks.
AdImageModeration ExtensionModeration, nillable Result of image review.
AdExtensions array of AdExtensionAdGetItem Extensions.
TextImageAdGet structure
Href string

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.

AdImageHash string

Hash of the image.

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

MobileAppImageAdGet structure
TrackingUrl string, nillable Tracking link for tracking app installations.
AdImageHash string

Hash of the image.

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

TextAdBuilderAdGet structure
Creative AdBuilderAdGetItem

A creative that was created in the Ad Builder.

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

Href string

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
Creative AdBuilderAdGetItem

A creative that was created in the Ad Builder.

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

TrackingUrl string, nillable Tracking link for tracking app installations.
CpcVideoAdBuilderAdGet structure
Creative AdBuilderAdGetItem

A creative that was created in the Ad Builder.

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

Href string

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
Creative AdBuilderAdGetItem

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.

Href string

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.

TrackingPixels array of TrackingPixelGetItem A Yandex.Audience pixel and/or an ADFOX, TNS, or Gemius impression tag.
AdBuilderAdGetItem structure
CreativeId long ID of the creative.
ThumbnailUrl string URL for the preview thumbnail.
PreviewUrl string URL for the preview image.
TrackingPixelGetItem structure
TrackingPixel string Link to a Yandex.Audience pixel or an ADFOX, TNS, or Gemius impression tag.
Provider string Provider of the pixel or impression tag.