--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/en/objects/keyword.md - https://yandex.com/dev/direct/doc/ru/objects/keyword.md - href: en/objects/keyword.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt sourcePath: en/dg/objects/keyword.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/en/llms.txt # Keyword 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). For more information, see [Keywords](https://yandex.com/support/direct/en/keywords/keywords.html) in the Help for Yandex Direct. 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](https://yandex.com/dev/direct/doc/en/objects/negative-keywords.md). A keyword can contain refining operators. See [Symbols and operators](https://yandex.com/support/direct/en/keywords/symbols-and-operators.html) in Yandex Direct Help. ## Service {#service} Use the [Keywords](https://yandex.com/dev/direct/doc/keywords/keywords.html) service for managing keywords. ### Methods {#methods} [add](https://yandex.com/dev/direct/doc/keywords/add.html) | [update](https://yandex.com/dev/direct/doc/keywords/update.html) | [delete](https://yandex.com/dev/direct/doc/keywords/delete.html) | [suspend](https://yandex.com/dev/direct/doc/keywords/suspend.html) | [resume](https://yandex.com/dev/direct/doc/keywords/resume.html) | [get](https://yandex.com/dev/direct/doc/keywords/get.html) {% note info %} Use the [KeywordBids](https://yandex.com/dev/direct/doc/keywordbids/keywordbids.html) service for setting bids and priorities on keywords. See also [Bid and priority (KeywordBid)](https://yandex.com/dev/direct/doc/en/objects/bid-priority.md). {% endnote %} ## Restrictions {#restrictions} You cannot add keywords to an ad group of the CPM_BANNER_AD_GROUP type and USER_PROFILE subtype, as well as an ad group of the DYNAMIC_TEXT_AD_GROUP type. To check the limit on the number of keywords per ad group for a user, call the [Clients](https://yandex.com/dev/direct/doc/clients/clients.html).[get](https://yandex.com/dev/direct/doc/clients/get.html) or [AgencyClients](https://yandex.com/dev/direct/doc/agencyclients/agencyclients.html).[get](https://yandex.com/dev/direct/doc/agencyclients/get.html) method (look for the KEYWORDS_TOTAL_PER_ADGROUP element in the [Restrictions](*Restrictions) array). For restrictions on the number of words and characters in a keyword, see the [Quantitative restrictions](https://yandex.com/support/direct/en/troubleshooting/interface.html#limitations) section in Yandex Direct Help. ## Status and state of a keyword {#status} The `Status` parameter reflects the results of reviewing a keyword. #| || **Status** | **Description** || || DRAFT | 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. || || ACCEPTED | The keyword was accepted after review. || || REJECTED | The keyword was rejected after review. || || UNKNOWN | The 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. #| || **State** | **Description** || || ON | Ad displays for the keyword are enabled. || || SUSPENDED | Ad displays were suspended by the owner using the [suspend](https://yandex.com/dev/direct/doc/keywords/suspend.html) method or in the web interface. || || OFF | The 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](https://yandex.com/dev/direct/doc/en/objects/adgroup.md#serving-status). ### Learn more - [How can I tell if there are active displays for a keyword?](https://yandex.com/dev/direct/doc/troubleshooting/faq.html#faq__keyword-running) ## Substitution variables {#userparams} 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](https://yandex.com/support/direct/en/statistics/url-tags.html) in Yandex Direct Help. ## Creating a new keyword after editing {#update} 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](https://yandex.com/dev/direct/doc/keywords/update.html) method returns the ID of the new keyword and a warning. Statistics remain available for the “old” keyword, but you can no longer manage this keyword or use it for impressions. ## Duplicate keywords {#duplicate} 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](https://yandex.com/dev/direct/doc/keywords/add.html) and [update](https://yandex.com/dev/direct/doc/keywords/update.html) 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. {% cut "Example" %} ![keywords-update](../_images/keywords-update.png) {% endcut %} - If editing two keywords using the `update` method causes the keywords to become duplicates and [a new keyword is created](#update), 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. {% cut "Example" %} ![keywords-update2](../_images/keywords-update2.png) {% endcut %} [*Restrictions]: **For an advertiser** Limits on the number of objects for an advertiser. **For an agency** —