A keyword determines which search queries on Yandex will trigger an ad impression, as well as the topics of pages and user interests that the ad will be displayed for in ad networks (the Yandex Advertising Network and external networks).

A keyword may contain negative keywords. You can also set negative keywords at the ad group level and at the campaign level. See Negative keywords.


Use the Keywords service for managing keywords.


add | update | delete | suspend | resume | get

Note. Use the Bids service for setting bids and priorities on keywords. See also Bid and priority (Bid).


Maximum of 200 keywords per ad group.

Keywords can't be added to a group for dynamic ads.

For restrictions on keywords, see Quantitative restrictions in the Help for Yandex.Direct.

Status and state of a keyword

The Status parameter reflects the results of reviewing a keyword.


New keyword: not yet submitted for review, or currently under review.

If a campaign has at least one ad that is active or submitted for review, new keywords are automatically submitted for review.

ACCEPTEDThe keyword was accepted after review.
REJECTEDThe keyword was rejected after review.
UNKNOWNThe status is unknown. This value is used for backward compatibility and for displaying statuses that are not supported in this version of the API.

The State parameter reflects whether displays were suspended for the keyword.


Ad displays for the keyword are enabled.

SUSPENDEDAd displays were suspended by the owner using the suspend method or in the web interface.
OFFThe keyword has not been submitted for review yet, or was rejected after review.

The ServingStatus parameter reflects the ad group serving status. See Ad group serving status.

Substitution variables

The ad link and sitelinks can use the substitution variables {param1} and {param2}. They are substituted with the values specified in the keyword parameters UserParam1 and UserParam2. This allows you to modify links depending on the keyword used to select and display the ad. For more information about substitution variables, see Transferring ad data in URLs in the Help for Yandex.Direct.

Creating a new keyword after editing

A new keyword may be created as the result of editing a keyword. For example, this may happen if you delete or replace a keyword or delete a negative keyword, or add or remove the ! or + operator.

If a new keyword is created, the update method returns the ID of the new keyword and a warning.

Statistics will still be available for the “old” keyword, but displays will be stopped for it, and you will not be able to work with it anymore.

Duplicate keywords

Duplicates are keywords that differ only in their word forms and auxiliary parts of speech, such as exchange dollars to rubles and exchanging rubles and dollars.

The add and update methods automatically delete duplicate keywords within an ad group:

  • If two keywords that are duplicates are passed in the input array of the add method, a single keyword is created, identical IDs are returned in the method response, and a warning is issued for one of the keywords.

  • If the input array of the add method passes a keyword that duplicates an existing one, the new keyword isn't created, and the method response returns the ID of the existing keyword with a warning.

  • If editing a keyword using the update method caused the keyword to become a duplicate of an existing one, the edited keyword is deleted and the method response returns the ID of the existing keyword with a warning.

  • If editing two keywords using the update method causes the keywords to become duplicates, one of them is deleted. The response for it returns the ID of the other keyword with a warning.

  • If editing two keywords using the update method causes the keywords to become duplicates and a new keyword is created, the method returns the ID of the new keyword and warnings: for one of the keywords in the request, that a new keyword was created, and for the other, that the same keyword exists.