--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/en/keywords/get.md - https://yandex.com/dev/direct/doc/ru/keywords/get.md - href: en/keywords/get.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt sourcePath: en/ref-v5/keywords/get.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/en/llms.txt # get This method returns parameters for keywords or autotargetings that match the specified criteria: the values of substitution variables, status and state, statistics for impressions and clicks, and bids. {% note alert %} We don't recommend requesting statistics on impressions and clicks for a large number of keywords: requests like this might take much longer to process. {% endnote %} You can get bids regardless of whether your campaign uses a manual or automatic strategy. ## Learn more - [How the "get" method works](https://yandex.ru/dev/direct/doc/en/best-practice/get.html) - [Autotargeting](https://yandex.ru/dev/direct/doc/dg/best-practice/auto-targeting.html) ## Restrictions {#restrictions} The method returns a maximum of 10,000 objects. ## Request {#input} Request structure in JSON format: ```javascript translate=no { "method": "get", "params": { /* params */ "SelectionCriteria": { /* KeywordsSelectionCriteria */ "Ids": [(long), ... ], "AdGroupIds": [(long), ... ], "CampaignIds": [(long), ... ], "States": [( "OFF" | "ON" | "SUSPENDED" ), ... ], "Statuses": [( "ACCEPTED" | "DRAFT" | "REJECTED"), ... ], "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ], "ModifiedSince": (string) }, /* required */ "FieldNames": [( "Id" | "Keyword" | "State" | "Status" | "ServingStatus" | "AdGroupId" | "CampaignId" | "Bid" | "AutotargetingSearchBidIsAuto" | "ContextBid" | "StrategyPriority" | "UserParam1" | "UserParam2" | "Productivity" | "StatisticsSearch" | "StatisticsNetwork" | "AutotargetingCategories" ), ... ], /* required */ "AutotargetingSettingsCategoriesFieldNames" : [ ("Exact"|"Narrow"|"Alternative"|"Accessory"|"Broader") ], "AutotargetingSettingsBrandOptionsFieldNames" : [ ("WithoutBrands"|"WithAdvertiserBrand"|"WithCompetitorsBrand") ], "Page": { /* LimitOffset */ "Limit": (long), "Offset": (long) } } } ``` #| || **Parameter** | **Type** | **Description** | **Required** || || **params structure (for JSON) / GetRequest (for SOAP)** || || `SelectionCriteria` | KeywordsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes || || `FieldNames` | array of KeywordFieldEnum | The names of parameters to get. {% note alert %} We don't recommend specifying the `StatisticsSearch` and `StatisticsNetwork` parameters when requesting data for a large number of keywords: requests like this take much longer to process. {% endnote %} | Yes || || `AutotargetingSettingsCategoriesFieldNames` | array of AutotargetingSettingsCategoriesFieldEnum | Targeting categories to get. | No || || `AutotargetingSettingsBrandOptionsFieldNames` | array of AutotargetingSettingsBrandOptionsFieldEnum | Brand mention settings to get. | No || || `Page` | [LimitOffset](https://yandex.ru/dev/direct/doc/en/best-practice/get.html) | Structure that defines the page for [paginated selection](https://yandex.ru/dev/direct/doc/en/best-practice/get.html) of data. | No || || **KeywordsSelectionCriteria structure** || || `Ids` | array of long | Selects keywords and autotargetings with the specified IDs. From 1 to 10,000 items in the array. | One of the parameters: `Ids`, `AdGroupIds`, or `CampaignIds` (or all may be present) || || `AdGroupIds` | array of long | Selects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array. || || `CampaignIds` | array of long | Selects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array. || || `States` | array of KeywordStatusSelectionEnum | Selects keywords and autotargetings with the specified states. See [Status and state of a keyword](https://yandex.ru/dev/direct/doc/en/objects/keyword). | No || || `Statuses` | array of StatusEnum | Selects keywords and autotargetings with the specified statuses. See [Status and state of a keyword](https://yandex.ru/dev/direct/doc/en/objects/keyword). | No || || `ServingStatuses` | array of ServingStatusEnum | Selects keywords and autotargetings with the specified ad group serving statuses. See [Serving status for the ad group](https://yandex.ru/dev/direct/doc/en/objects/adgroup). | No || || `ModifiedSince` | string | Selects keywords and autotargetings that had changes starting from the specified date. Specified in the format `YYYY-MM-DDThh:mm:ssZ` (following ISO 8601), such as `2015-05-24T23:59:59Z`. | No || |# ## Response {#output} {% note info %} The response contains only those parameters that were indicated in the `FieldNames` input parameter. {% endnote %} Response structure in JSON format: ```javascript translate=no { "result": { /* result */ "Keywords": [{ /* KeywordGetItem */ "Id": (long), "Keyword": (string), "AdGroupId": (long), "CampaignId": (long), "UserParam1": (string), /* nillable */ "UserParam2": (string), /* nillable */ "Bid": (long), "AutotargetingSearchBidIsAuto" : ("YES"|"NO"), "ContextBid": (long), "StrategyPriority": "NORMAL", /* nillable */ "State": ( "OFF" | "ON" | "SUSPENDED" ), "Status": ( "ACCEPTED" | "DRAFT" | "REJECTED" | "UNKNOWN" ), "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ), "Productivity": null, "StatisticsSearch": { /* Statistics */ "Clicks": (long), /* required */ "Impressions": (long) /* required */ }, "StatisticsNetwork": { /* Statistics */ "Clicks": (long), /* required */ "Impressions": (long) /* required */ }, "AutotargetingCategories" : { /* nillable */ "Items" : [{ /* required */ "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */, "Value" : ("YES"|"NO") /* required */ }, ...], "AutotargetingSettings" : { /* nillable */ "Categories" : { "Exact" : ("YES"|"NO"), "Narrow" : ("YES"|"NO"), "Alternative" : ("YES"|"NO"), "Accessory" : ("YES"|"NO"), "Broader" : ("YES"|"NO") }, "BrandOptions" : { "WithoutBrands" : ("YES"|"NO"), "WithAdvertiserBrand" : ("YES"|"NO"), "WithCompetitorsBrand" : ("YES"|"NO") } } }, ... ], "LimitedBy": (long) } } } ``` #| || **Parameter** | **Type** | **Description** || || **result structure (for JSON) / GetResponse (for SOAP)** || || `Keywords` | array of KeywordGetItem | Keywords and autotargetings. || || `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](https://yandex.ru/dev/direct/doc/en/best-practice/get.html). || || **KeywordGetItem structure** || || `Id` | long | ID of the keyword or autotargeting. || || `AdGroupId` | long | ID of the ad group that the keyword or autotargeting is associated with. || || `CampaignId` | long | ID of the campaign that the keyword or autotargeting is associated with. || || `Keyword` | string | Keywords. May contain negative keywords. For autotargeting, the value `---autotargeting` is returned. || || `UserParam1` | string, nillable | Value of the `{param1}` [substitution variable](https://yandex.ru/dev/direct/doc/en/objects/keyword). Maximum of 255 characters. || || `UserParam2` | string, nillable | Value of the `{param2}` [substitution variable](https://yandex.ru/dev/direct/doc/en/objects/keyword). Maximum of 255 characters. || || `Bid` | long | Bid in search results. || || `AutotargetingSearchBidIsAuto` | YesNoEnum | A flag indicating whether [automatic bid](https://yandex.ru/support/direct/en/impression-criteria/autotargeting#autotargeting__auto-bids) is enabled. || || `ContextBid` | long | Bid in ad networks. || || `StrategyPriority` | PriorityEnum, nillable | Priority of the keyword or autotargeting: NORMAL. || || `Status` | StatusEnum | Status of the keyword or autotargeting. For a description of the statuses, see the section [Status and state of a keyword](https://yandex.ru/dev/direct/doc/en/objects/keyword). || || `ServingStatus` | ServingStatusEnum | Serving status for the ad group. For a description of the statuses, see the section [Serving status for the ad group](https://yandex.ru/dev/direct/doc/en/objects/adgroup). || || `State` | StateEnum | State of the keyword or autotargeting. For a description of the states, see the section [Status and state of a keyword](https://yandex.ru/dev/direct/doc/en/objects/keyword). || || `Productivity` | Productivity, nillable | This parameter is obsolete. Always returns null (nil). || || `StatisticsSearch` | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword or autotargeting in search results. If the ad group has very few impressions (the `ServingStatus` parameter specifies RARELY_SERVED), the parameter isn't returned. || || `StatisticsNetwork` | Statistics | Statistics on impressions and clicks for all the group's ads for this keyword in ad networks. If the ad group has very few displays (the `ServingStatus` parameter has the value RARELY_SERVED), the parameter isn't returned. || || `AutotargetingCategories` | AutotargetingCategories, nillable | Targeting categories. {% note alert %} This field is deprecated and will soon cease to be supported. You can retrieve the targeting settings using the `AutotargetingSettings` structure. {% endnote %} || || `AutotargetingSettings` | AutotargetingSettings, nillable | Targeting settings. || || **Statistics structure** || || `Clicks` | long | Number of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. || || `Impressions` | long | Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. || || **AutotargetingCategories structure** || || `Category` | AutotargetingCategoriesEnum | Targeting category: - EXACT: The targeted queries. The ad is highly relevant to the user's search. - ALTERNATIVE: Alternative queries. The user is searching for a product that can be replaced by the promoted product. The ad might also match the query in this case. - COMPETITOR: Queries that mention your competitors. The user is looking for the promoted product via competitor brands. - BROADER: Broad queries. Queries that show interest in a product type your offer belongs to. - ACCESSORY: Related queries. Queries for products that may be of interest alongside the promoted product or service. {% note alert %} This field is deprecated and will soon cease to be supported. The settings specified in the web interface are converted for the API as follows: #| || **Web interface** | **API** || || At least one enabled "Exact" or "Narrow" category. | Enabled `EXACT` category. || || Enabled Competitors brand mention option (provided it's the only brand mention option enabled). | Enabled `COMPETITOR` category + the other categories are disabled. || || Enabled Competitors brand mention option (provided it isn't the only brand mention option enabled). | Enabled `COMPETITOR` category. || || Disabled Competitors brand mention option. | Disabled `COMPETITOR` category. || |# {% endnote %} || || `Value` | YesNoEnum | The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default. || || **AutotargetingSettings structure** || || `Categories` | AutotargetingSettingsCategoriesFieldNames | Targeting categories. Available options: - Exact: Targeted queries. The ad is highly relevant to the user's search. - Narrow: Narrow queries. The ad is broader than the user's search. - Alternative: Alternative queries. The user is searching for a product that can be replaced by the promoted product. The ad might also meet the query in this case. - Accessory: Related queries. Queries for products that may be of interest alongside the promoted product or service. - Broader: Broad queries. Queries that show interest in a product type your offer belongs to. || || `BrandOptions` | AutotargetingSettingsBrandOptionsFieldNames | Brand mention settings. Available options: - WithoutBrands: Non-branded queries. - WithAdvertiserBrand: Queries mentioning your brand. - WithCompetitorsBrand: Queries mentioning competitor brands. || |#