Documentation

get

Returns parameters of ads 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[

Criteria for selecting ads.

Required

Yes

]no-highlight]
": { /* AdsSelectionCriteria */ "Ids
[no-highlight[

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

Required

At least one of the parameters CampaignIds, AdGroupIds, or Ids (or all may be present)

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

Selects ads based on the specified states. See Ad status and state.

Required

No

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

“OFF“ | “ON“ | “SUSPENDED“ | “OFF_BY_MONITORING“ | “ARCHIVED“

]no-highlight]
| "ARCHIVED" ), ... ], "Statuses
[no-highlight[

Selects ads based on the specified statuses. See Ad status and state.

Required

No

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “PREACCEPTED“ | “REJECTED“

]no-highlight]
| "REJECTED" ), ... ], "CampaignIds
[no-highlight[

Selects ads from the specified campaigns. From 1 to 10 items in the array.

Required

At least one of the parameters CampaignIds, AdGroupIds, or Ids (or all may be present)

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

Selects ads from the specified groups. From 1 to 1000 items in the array.

Required

At least one of the parameters CampaignIds, AdGroupIds, or Ids (or all may be present)

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

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.

Required

No

]no-highlight]
": [( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD" ), ... ], "Mobile
[no-highlight[

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.

Required

No

]no-highlight]
": ( "YES" | "NO" ), "VCardIds
[no-highlight[

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.

Required

No

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

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.

Required

No

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

Selects ads with the specified images. From 1 to 50 items in the array.

Required

No

]no-highlight]
": [(string), ... ], "VCardModerationStatuses
[no-highlight[

Selects ads based on results of vCard review. For a description of the statuses, see the section Add-ons.

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.

Required

No

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“

]no-highlight]
| "REJECTED" ), ... ], "SitelinksModerationStatuses
[no-highlight[

Selects ads based on results of sitelink review: For a description of the statuses, see the section Add-ons.

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.

Required

No

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“

]no-highlight]
| "REJECTED" ), ... ], "AdImageModerationStatuses
[no-highlight[

Selects ads based on results of image review. For a description of the statuses, see the section Add-ons.

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.

Required

No

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“

]no-highlight]
| "REJECTED" ), ... ], "AdExtensionIds
[no-highlight[

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.

Required

No

]no-highlight]
": [(long), ... ] }, /* required */ "FieldNames
[no-highlight[

Names of top-level parameters to get.

Required

Yes

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

“AdCategories“ | “AgeLabel“ | “AdGroupId“ | “CampaignId“ | “Id“ | “State“ | “Status“ | “StatusClarification“ | “Type“ | “Subtype“

]no-highlight]
| "Subtype" ), ... ], /* required */ "TextAdFieldNames
[no-highlight[

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.

Required

No

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

“Title“ | “Title2“ | “Text“ | “Href“ | “Mobile“ | “DisplayDomain“ | “DisplayUrlPath“ | “DisplayUrlPathModeration“ | “VCardId“ | “VCardModeration“ | “SitelinkSetId“ | “SitelinksModeration“ | “AdImageHash“ | “AdImageModeration“ | “AdExtensions“ | “VideoExtension“

]no-highlight]
| "VideoExtension" ), ... ], "MobileAppAdFieldNames
[no-highlight[

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

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

Required

No

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

“Title“ | “Text“ | “Features“ | “Action“ | “AdImageHash“ | “AdImageModeration“ | “TrackingUrl“

]no-highlight]
| "TrackingUrl" ), ... ], "DynamicTextAdFieldNames
[no-highlight[

Names of parameters to get for a dynamic ad. See Ad type.

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

Required

No

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

“Text“ | “VCardId“ | “VCardModeration“ | “SitelinkSetId“ | “SitelinksModeration“ | “AdImageHash“ | “AdImageModeration“ | “AdExtensions“

]no-highlight]
| "AdExtensions" )], "TextImageAdFieldNames
[no-highlight[

Names of parameters to get for an image ad that was created from an image (in a group of text and image ads). See Ad type.

Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from TextImageAdFieldNames are not returned.

Required

No

]no-highlight]
": [( "AdImageHash" | "Href" ), ... ], "MobileAppImageAdFieldNames
[no-highlight[

Names of parameters to get for an image ad that was created from an image (in a group of mobile app ads). See Ad type.

Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from MobileAppImageAdFieldNames are not returned.

Required

No

]no-highlight]
": [( "AdImageHash" | "TrackingUrl" ), ... ], "TextAdBuilderAdFieldNames
[no-highlight[

Names of parameters to get for an image ad that was created from a creative (in a group of text and image ads). See Ad type.

Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from TextAdBuilderAdFieldNames are not returned.

Required

No

]no-highlight]
": [( "Creative" | "Href" ), ... ], "MobileAppAdBuilderAdFieldNames
[no-highlight[

Names of parameters to get for an image ad that was created from a creative (in a group of mobile app ads). See Ad type.

Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from MobileAppAdBuilderAdFieldNames are not returned.

Required

No

]no-highlight]
": [( "Creative" | "TrackingUrl" ), ... ], "Page
[no-highlight[

Structure that defines the page for paginated selection of data.

Required

No

]no-highlight]
": { /* 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 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
MobileAppAdFieldNames array of MobileAppAdFieldEnumNames of parameters to get for a mobile app ad. See Ad type.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from MobileAppAdFieldNames are not returned.
No
DynamicTextAdFieldNames array of DynamicTextAdFieldEnumNames of parameters to get for a dynamic ad. See Ad type.
Note. If a different type of ad is selected according to SelectionCriteria, parameters from DynamicTextAdFieldNames are not returned.
No
TextImageAdFieldNames array of TextImageAdFieldEnumNames of parameters to get for an image ad that was created from an image (in a group of text and image ads). See Ad type.
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 MobileAppImageAdFieldEnumNames of parameters to get for an image ad that was created from an image (in a group of mobile app ads). See Ad type.
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 TextAdBuilderAdFieldEnumNames of parameters to get for an image ad that was created from a creative (in a group of text and image ads). See Ad type.
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 MobileAppAdBuilderAdFieldEnumNames of parameters to get for an image ad that was created from a creative (in a group of mobile app ads). See Ad type.
Note. If a different type or subtype of ad is selected according to SelectionCriteria, the parameters from MobileAppAdBuilderAdFieldNames are not returned.
No
Page LimitOffset

Structure that defines the page for paginated selection of data.

No
AdsSelectionCriteria structure
Ids array 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)
AdGroupIds array of longSelects ads from the specified groups. From 1 to 1000 items in the array.
CampaignIds array of longSelects ads from the specified campaigns. From 1 to 10 items in the array.
States array of AdStateSelectionEnumSelects ads based on the specified states. See Ad status and state.No
Statuses array of AdStatusSelectionEnumSelects 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 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
SitelinkSetIds array 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
AdImageHashes array of stringSelects ads with the specified images. From 1 to 50 items in the array.No
VCardModerationStatuses array of ExtensionStatusSelectionEnumSelects ads based on results of vCard review. For a description of the statuses, see the section Add-ons.

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 ExtensionStatusSelectionEnumSelects ads based on results of sitelink review: For a description of the statuses, see the section Add-ons.

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 ExtensionStatusSelectionEnumSelects ads based on results of image review. For a description of the statuses, see the section Add-ons.

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 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": { 
    "Ads
[no-highlight[

Ads.

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

The ad ID.

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

ID of the campaign that the ad belongs to.

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

ID of the group that the ad belongs to.

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

Status of the ad. For a description of the statuses, see the section Ad status and state.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “PREACCEPTED“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), "State
[no-highlight[

State of the ad. For a description of the states, see the section Ad status and state.

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

“OFF“ | “ON“ | “SUSPENDED“ | “OFF_BY_MONITORING“ | “ARCHIVED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), "StatusClarification
[no-highlight[

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

]no-highlight]
": (string), "AdCategories
[no-highlight[Special category.]no-highlight]
": { /* ArrayOfAdCategoryEnum */ "Items": [( "ABORTION" | ...
[no-highlight[

“ABORTION“ | “ALCOHOL“ | “BABY_FOOD“ | “DIETARY_SUPPLEMENTS“ | “MEDICINE“ | “PROJECT_DECLARATION“ | “PSEUDO_WEAPON“ | “TOBACCO“

]no-highlight]
| "TOBACCO" ), ... ] /* required */ }, /* nillable */ "AgeLabel
[no-highlight[Age label.]no-highlight]
": ( "AGE_0" | ...
[no-highlight[

“AGE_0“ | “AGE_6“ | “AGE_12“ | “AGE_16“ | “AGE_18“ | “MONTHS_0“ | “MONTHS_1“ | “MONTHS_2“ | “MONTHS_3“ | “MONTHS_4“ | “MONTHS_5“ | “MONTHS_6“ | “MONTHS_7“ | “MONTHS_8“ | “MONTHS_9“ | “MONTHS_10“ | “MONTHS_11“ | “MONTHS_12“

]no-highlight]
| "MONTHS_12"), /* nillable */ "Type
[no-highlight[

Type of ad. See Ad type.

]no-highlight]
": ( "TEXT_AD" | "MOBILE_APP_AD" | "DYNAMIC_TEXT_AD" | "IMAGE_AD" ), "Subtype
[no-highlight[

The ad subtype. For ads with a type other than IMAGE_AD, the value NONE is returned.

]no-highlight]
": ( "NONE" | "TEXT_IMAGE_AD" | "MOBILE_APP_IMAGE_AD" | "TEXT_AD_BUILDER_AD" | "MOBILE_APP_AD_BUILDER_AD" ), "TextAd
[no-highlight[

Parameters of a text and image ad. See Ad type.

]no-highlight]
": { /* TextAdGet */ "Title
[no-highlight[

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.

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

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.

]no-highlight]
": (string), /* nillable */ "Text
[no-highlight[

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.

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

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.

]no-highlight]
": (string), /* nillable */ "Mobile
[no-highlight[

Indicates whether this is a mobile ad: YES or NO. See Mobile ads in the Help for Yandex.Direct.

]no-highlight]
": ( "YES" | "NO" ), "DisplayDomain
[no-highlight[

Domain being advertised. Detected automatically from the ad link.

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

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.

]no-highlight]
": (string), /* nillable */ "VCardId
[no-highlight[

ID of the vCard. The vCard must belong to the same campaign as the ad.

]no-highlight]
": (long), /* nillable */ "AdImageHash
[no-highlight[

Hash of the image.

For text and image ads, only images with the REGULAR or WIDE type are acceptable. See Type of image.]no-highlight]
": (string), /* nillable */ "SitelinkSetId
[no-highlight[

ID of a set of sitelinks. Allowed only with the Href parameter.

]no-highlight]
": (long), /* nillable */ "DisplayUrlPathModeration
[no-highlight[

Result of reviewing the display link.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Result of vCard review.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Result of reviewing the set of sitelinks.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Result of image review.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Extensions.

]no-highlight]
": [{ /* AdExtensionAdGetItem */ "AdExtensionId
[no-highlight[

Extension ID.

]no-highlight]
": (long), /* required */ "Type
[no-highlight[

Extension type. Only one type of extension is available at this time — the “Callout” (CALLOUT).

]no-highlight]
": ( "CALLOUT" | "UNKNOWN" ) /* required */ }, ... ], "VideoExtension
[no-highlight[

Video extension.

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

]no-highlight]
": { /* VideoExtensionGetItem */ "CreativeId
[no-highlight[

ID of the creative.

]no-highlight]
": (long), /* required */ "Status
[no-highlight[

Result of reviewing the video extension assignment to the ad. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), "ThumbnailUrl
[no-highlight[

URL for the preview image.

]no-highlight]
": (string), /* required */ "PreviewUrl
[no-highlight[

URL for the preview video.

]no-highlight]
": (string) /* required */ } /* nillable */ }, "MobileAppAd
[no-highlight[

Parameters of a mobile app ad. See Ad type.

]no-highlight]
": { /* MobileAppAdGet */ "Title
[no-highlight[

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.

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

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.

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

Tracking link for tracking app installations.

]no-highlight]
": (string), /* nillable */ "Features
[no-highlight[

Add-ons that need to be automatically downloaded from the app store and displayed in the ad.

]no-highlight]
": [{ /* MobileAppAdFeatureGetItem */ "IsAvailable
[no-highlight[

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.
]no-highlight]
": ( "YES" | "NO" | "UNKNOWN" ), /* required */ "Feature
[no-highlight[

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.
]no-highlight]
": ( "PRICE" | "ICON" | "CUSTOMER_RATING" | "RATINGS" ), /* required */ "Enabled
[no-highlight[

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.
]no-highlight]
": ( "YES" | "NO" ) /* required */ }, ... ], "Action
[no-highlight[

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.

]no-highlight]
": ( "DOWNLOAD" | "GET" | "INSTALL" | "MORE" | "OPEN" | "UPDATE" | "PLAY" | "BUY_AUTODETECT" ), "AdImageHash
[no-highlight[

Hash of the image.

For mobile app ads, only images with the WIDE type are acceptable. See Type of image.

]no-highlight]
": (string), /* nillable */ "AdImageModeration
[no-highlight[

Result of image review.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Parameters of a dynamic ad. See Ad type.

]no-highlight]
": { /* DynamicTextAdGet */ "Text
[no-highlight[

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.

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

ID of the vCard. The vCard must belong to the same campaign as the ad.

]no-highlight]
": (long), /* nillable */ "AdImageHash
[no-highlight[

Hash of the image.

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

]no-highlight]
": (string), /* nillable */ "SitelinkSetId
[no-highlight[

ID of a set of sitelinks. Allowed only with the Href parameter.

]no-highlight]
": (long), /* nillable */ "VCardModeration
[no-highlight[

Result of vCard review.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Result of reviewing the set of sitelinks.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Result of image review.

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

Result of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.

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

“ACCEPTED“ | “DRAFT“ | “MODERATION“ | “REJECTED“ | “UNKNOWN“

]no-highlight]
| "UNKNOWN" ), /* required */ "StatusClarification
[no-highlight[

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

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

Extensions.

]no-highlight]
": [{ /* AdExtensionAdGetItem */ "AdExtensionId
[no-highlight[

Extension ID.

]no-highlight]
": (long), /* required */ "Type
[no-highlight[

Extension type. Only one type of extension is available at this time — the “Callout” (CALLOUT).

]no-highlight]
": ( "CALLOUT" | "UNKNOWN" ) /* required */ }, ... ] }, "TextImageAd
[no-highlight[

Parameters of an image ad that was created from an image (in a group of text and image ads). See Ad type.

]no-highlight]
": { /* TextImageAdGet */ "Href
[no-highlight[

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.

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

Hash of the image.

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

]no-highlight]
": (string) }, "MobileAppImageAd
[no-highlight[

Parameters of an image ad that was created from an image (in a group of mobile app ads). See Ad type.

]no-highlight]
": { /* MobileAppImageAdGet */ "TrackingUrl
[no-highlight[

Tracking link for tracking app installations.

]no-highlight]
": (string), /* nillable */ "AdImageHash
[no-highlight[

Hash of the image.

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

]no-highlight]
": (string) }, "TextAdBuilderAd
[no-highlight[

Parameters of an image ad that was created from a creative (in a group of text and image ads). See Ad type.

]no-highlight]
": { /* TextAdBuilderAdGet */ "Creative
[no-highlight[

A creative that was created in the Ad Builder.

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

]no-highlight]
": { /* AdBuilderAdGetItem */ "CreativeId
[no-highlight[

ID of the creative.

]no-highlight]
": (long), /* required */ "ThumbnailUrl
[no-highlight[

URL for the preview thumbnail.

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

URL for the preview image.

]no-highlight]
": (string) }, "Href
[no-highlight[

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.

]no-highlight]
": (string) }, "MobileAppAdBuilderAd
[no-highlight[

Parameters of an image ad that was created from a creative (in a group of mobile app ads). See Ad type.

]no-highlight]
": { /* MobileAppAdBuilderAdGet */ "Creative
[no-highlight[

A creative that was created in the Ad Builder.

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

]no-highlight]
": { /* AdBuilderAdGetItem */ "CreativeId
[no-highlight[

ID of the creative.

]no-highlight]
": (long), /* required */ "ThumbnailUrl
[no-highlight[

URL for the preview thumbnail.

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

URL for the preview image.

]no-highlight]
": (string) }, "TrackingUrl
[no-highlight[

Tracking link for tracking app installations.

]no-highlight]
": (string) /* nillable */ } }, ... ], "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) } }

Parameters are described below.

Parameter Type Description
result structure (for JSON) / GetResponse (for SOAP)
Ads array of AdGetItemAds.
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.
AdGetItem structure
Id longThe ad ID.
CampaignId longID of the campaign that the ad belongs to.
AdGroupId longID of the group that the ad belongs to.
Status StatusEnumStatus of the ad. For a description of the statuses, see the section Ad status and state.
StatusClarification string

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

State StateEnumState of the ad. For a description of the states, see the section Ad status and state.
AdCategories ArrayOfString
[no-highlight[

Object containing an array of Items strings

]no-highlight]
, nillable
Special category.
AgeLabel AgeLabelEnum, nillableAge label.
Type AdTypeEnumType of ad. See Ad type.
Subtype AdSubtypeEnumThe 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. See Ad type.
MobileAppAd MobileAppAdGet Parameters of a mobile app ad. See Ad type.
DynamicTextAd DynamicTextAdGet Parameters of a dynamic ad. See Ad type.
TextImageAd TextImageAdGet Parameters of an image ad that was created from an image (in a group of text and image ads). See Ad type.
MobileAppImageAd MobileAppImageAdGet Parameters of an image ad that was created from an image (in a group of mobile app ads). See Ad type.
TextAdBuilderAd TextAdBuilderAdGet Parameters of an image ad that was created from a creative (in a group of text and image ads). See Ad type.
MobileAppAdBuilderAd MobileAppAdBuilderAdGet Parameters of an image ad that was created from a creative (in a group of mobile app ads). See Ad type.
TextAdGet structure
Title string

Title 1.

Maximum of 35 characters not counting "narrow
[no-highlight[“Narrow” characters are: !,.;:“]no-highlight]
" 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
[no-highlight[“Narrow” characters are: !,.;:“]no-highlight]
" 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
[no-highlight[“Narrow” characters are: !,.;:“]no-highlight]
" 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 YesNoEnumIndicates whether this is a mobile ad: YES or NO. See Mobile ads in the Help for Yandex.Direct.
DisplayDomain stringDomain 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, nillableID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetId long, nillableID 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 Type of image.
DisplayUrlPathModeration ExtensionModeration, nillableResult of reviewing the display link.
VCardModeration ExtensionModeration, nillableResult of vCard review.
SitelinksModeration ExtensionModeration, nillableResult of reviewing the set of sitelinks.
AdImageModeration ExtensionModeration, nillableResult of image review.
AdExtensions array of AdExtensionAdGetItemExtensions.
VideoExtension VideoExtensionGetItem, nillable

Video extension.

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

ExtensionModeration structure
Status StatusEnumResult of reviewing the association between an ad and an add-on. For a description of the statuses, see the section Add-ons.
StatusClarification stringText explanation of the status and/or reasons for rejection after review.
AdExtensionAdGetItem structure
AdExtensionId longExtension ID.
Type AdExtensionTypeEnumExtension type. Only one type of extension is available at this time — the “Callout” (CALLOUT).
VideoExtensionGetItem structure
CreativeId longID of the creative.
Status StatusEnumResult of reviewing the video extension assignment to the ad. For a description of the statuses, see the section Add-ons.
ThumbnailUrl stringURL for the preview image.
PreviewUrl stringURL 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 MobileAppAdFeatureGetItemAdd-ons that need to be automatically downloaded from the app store and displayed in the ad.
TrackingUrl string, nillableTracking 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 Type of image.

AdImageModeration ExtensionModeration, nillableResult 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
[no-highlight[“Narrow” characters are: !,.;:“]no-highlight]
" 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, nillableID of the vCard. The vCard must belong to the same campaign as the ad.
SitelinkSetId long, nillableID of a set of sitelinks. Allowed only with the Href parameter.
AdImageHash string, nillable

Hash of the image.

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

VCardModeration ExtensionModeration, nillableResult of vCard review.
SitelinksModeration ExtensionModeration, nillableResult of reviewing the set of sitelinks.
AdImageModeration ExtensionModeration, nillableResult of image review.
AdExtensions array of AdExtensionAdGetItemExtensions.
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 Type of image.

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

Hash of the image.

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

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, nillableTracking link for tracking app installations.
AdBuilderAdGetItem structure
CreativeId longID of the creative.
ThumbnailUrl stringURL for the preview thumbnail.
PreviewUrl stringURL for the preview image.