get

Returns parameters of keywords or autotargetings that match the set criteria: the values of substitution variables, status and state, statistics for impressions and clicks, and bids and priorities.

  1. Restrictions
  2. Request
  3. Response
Attention. 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.

You can get bids and priorities regardless of whether a manual or automatic strategy is selected in the campaign.

Attention.
  • Bids and prices are passed via the Yandex Direct API as integer numbers. The value passed is a bid or price multiplied by 1,000,000.

  • All bids and prices are shown in the advertiser's currency.

Restrictions

The method returns a maximum of 10,000 objects.

You can't get keywords from archived campaigns.

Request

Request structure in JSON format:

{
  "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 */
    "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.

Attention. 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.
Yes
Page LimitOffset

Structure that defines the page for paginated selection 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. No
Statuses array of StatusEnum Selects keywords and autotargetings with the specified statuses. See Status and state of a keyword. No
ServingStatuses array of ServingStatusEnum Selects keywords and autotargetings with the specified ad group serving statuses. See Ad group serving status. No
ModifiedSince string

Selects keywords and autotargetings that had changes starting from the specified date.

Specified in YYYY-MM-DDThh:mm:ssZ format (conforming to ISO 8601), such as 2015-05-24T23:59:59Z.

No
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.

Attention. 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.
Yes
Page LimitOffset

Structure that defines the page for paginated selection 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. No
Statuses array of StatusEnum Selects keywords and autotargetings with the specified statuses. See Status and state of a keyword. No
ServingStatuses array of ServingStatusEnum Selects keywords and autotargetings with the specified ad group serving statuses. See Ad group serving status. No
ModifiedSince string

Selects keywords and autotargetings that had changes starting from the specified date.

Specified in YYYY-MM-DDThh:mm:ssZ format (conforming to ISO 8601), such as 2015-05-24T23:59:59Z.

No

Response

Note. The response contains only those parameters that were indicated in the FieldName input parameter.

Response structure in JSON format:

{
  "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": ( "LOW" | "NORMAL" | "HIGH" ), /* 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 */
         }, ...]        
    }, ... ],
    "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 Paginated selection.
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 The value of the {param1} substitution variable. Maximum of 255 characters.
UserParam2 string, nillable The value of the {param2} substitution variable. Maximum of 255 characters.
Bid long Bid in search results.
AutotargetingSearchBidIsAuto YesNoEnum A flag indicating whether automatic bid is enabled.
ContextBid long

Bid in ad networks.

StrategyPriority PriorityEnum, nillable

Priority of the keyword or autotargeting: LOW, NORMAL or HIGH.

Status StatusEnum Status of the keyword or autotargeting. For status descriptions, see Status and state of a keyword.
ServingStatus ServingStatusEnum Serving status for the ad group. For status descriptions, see Ad group serving status.
State StateEnum State of the keyword or autotargeting. For state descriptions, see Status and state of a 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 displays (the ServingStatus parameter has the value 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.

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 perfectly matches user queries.
  • ALTERNATIVE: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
  • COMPETITOR: Queries mentioning competitors. Searching competitors for the advertised product.
  • BROADER: Broad queries. Queries showing interest in a product exemplified by the ad.
  • ACCESSORY: Related queries. Queries for products that might interest the user in relation to the advertised product or service.
Attention.

This field is deprecated and will soon stop being supported.

Your settings from the web interface are converted for the API as follows:

Web interface API

Enabled “Targeted” or “Narrow” category.

Enabled EXACT category.

Enabled “Competitors” brand mention option (if this is the only enabled brand mention option).

Enabled COMPETITOR category + all other categories are disabled.

Enabled “Competitors” brand mention option (if this isn't the only enabled brand mention option).

Enabled COMPETITOR category.

Disabled “Competitors” brand mention option.

Disabled COMPETITOR category.

Web interface API

Enabled “Targeted” or “Narrow” category.

Enabled EXACT category.

Enabled “Competitors” brand mention option (if this is the only enabled brand mention option).

Enabled COMPETITOR category + all other categories are disabled.

Enabled “Competitors” brand mention option (if this isn't the only enabled brand mention option).

Enabled COMPETITOR category.

Disabled “Competitors” brand mention option.

Disabled COMPETITOR category.

Value YesNoEnum The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default.
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 Paginated selection.
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 The value of the {param1} substitution variable. Maximum of 255 characters.
UserParam2 string, nillable The value of the {param2} substitution variable. Maximum of 255 characters.
Bid long Bid in search results.
AutotargetingSearchBidIsAuto YesNoEnum A flag indicating whether automatic bid is enabled.
ContextBid long

Bid in ad networks.

StrategyPriority PriorityEnum, nillable

Priority of the keyword or autotargeting: LOW, NORMAL or HIGH.

Status StatusEnum Status of the keyword or autotargeting. For status descriptions, see Status and state of a keyword.
ServingStatus ServingStatusEnum Serving status for the ad group. For status descriptions, see Ad group serving status.
State StateEnum State of the keyword or autotargeting. For state descriptions, see Status and state of a 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 displays (the ServingStatus parameter has the value 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.

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 perfectly matches user queries.
  • ALTERNATIVE: Alternative queries. The user is looking for a product that can be replaced by the advertised product. The ad might also match the query in this case.
  • COMPETITOR: Queries mentioning competitors. Searching competitors for the advertised product.
  • BROADER: Broad queries. Queries showing interest in a product exemplified by the ad.
  • ACCESSORY: Related queries. Queries for products that might interest the user in relation to the advertised product or service.
Attention.

This field is deprecated and will soon stop being supported.

Your settings from the web interface are converted for the API as follows:

Web interface API

Enabled “Targeted” or “Narrow” category.

Enabled EXACT category.

Enabled “Competitors” brand mention option (if this is the only enabled brand mention option).

Enabled COMPETITOR category + all other categories are disabled.

Enabled “Competitors” brand mention option (if this isn't the only enabled brand mention option).

Enabled COMPETITOR category.

Disabled “Competitors” brand mention option.

Disabled COMPETITOR category.

Web interface API

Enabled “Targeted” or “Narrow” category.

Enabled EXACT category.

Enabled “Competitors” brand mention option (if this is the only enabled brand mention option).

Enabled COMPETITOR category + all other categories are disabled.

Enabled “Competitors” brand mention option (if this isn't the only enabled brand mention option).

Enabled COMPETITOR category.

Disabled “Competitors” brand mention option.

Disabled COMPETITOR category.

Value YesNoEnum The flag indicating that the specified targeting category is enabled. All targeting categories are enabled by default.