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 that is passed represents the 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" | "ContextBid" | "StrategyPriority" | "UserParam1" | "UserParam2" | "Productivity" | "StatisticsSearch" | "StatisticsNetwork" ), ... ], /* 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 Serving status for the ad group. No
ModifiedSince string

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

Specified in the format YYYY-MM-DDThh:mm:ssZ (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), 
      "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 */
      }        
    }, ... ],
    "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.
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. Maximum of 255 characters.
UserParam2 string, nillable Value of the {param2} substitution variable. Maximum of 255 characters.
Bid long Bid in search results.
ContextBid long

Bid in ad networks.

For autotargeting, this parameter isn't returned.

StrategyPriority PriorityEnum, nillable Priority of the keyword or autotargeting: LOW, NORMAL or HIGH.
Status StatusEnum Status of the keyword or autotargeting. For a description of the statuses, see the section Status and state of a keyword.
ServingStatus ServingStatusEnum Serving status for the ad group. For a description of the statuses, see the section Serving status for the ad group.
State StateEnum State of the keyword or autotargeting. For a description of the states, see the section 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.

For autotargeting, this parameter isn't returned.

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.