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)
    }
  } 
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteriaKeywordsSelectionCriteria

Criteria for selecting keywords and autotargetings.

Yes
FieldNamesarray 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
PageLimitOffset

Structure that defines the page for paginated selection of data.

No
KeywordsSelectionCriteria structure
Idsarray of longSelects 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)
AdGroupIdsarray of longSelects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array.
CampaignIdsarray of longSelects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array.
Statesarray of KeywordStatusSelectionEnumSelects keywords and autotargetings with the specified states. See Status and state of a keyword.No
Statusesarray of StatusEnumSelects keywords and autotargetings with the specified statuses. See Status and state of a keyword.No
ServingStatusesarray of ServingStatusEnumSelects keywords and autotargetings with the specified ad group serving statuses. See Serving status for the ad group.No
ModifiedSincestring

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)
  }
}
ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
Keywordsarray of KeywordGetItemKeywords and autotargetings.
LimitedBylongSequential 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
IdlongID of the keyword or autotargeting.
AdGroupIdlongID of the ad group that the keyword or autotargeting is associated with.
CampaignIdlongID of the campaign that the keyword or autotargeting is associated with.
Keywordstring

Keywords. May contain negative keywords.

For autotargeting, the value ---autotargeting is returned.

UserParam1string, nillableValue of the {param1} substitution variable. Maximum of 255 characters.
UserParam2string, nillableValue of the {param2} substitution variable. Maximum of 255 characters.
BidlongBid in search results.
ContextBidlong

Bid in ad networks.

For autotargeting, this parameter isn't returned.

StrategyPriorityPriorityEnum, nillablePriority of the keyword or autotargeting: LOW, NORMAL or HIGH.
StatusStatusEnumStatus of the keyword or autotargeting. For a description of the statuses, see the section Status and state of a keyword.
ServingStatusServingStatusEnumServing status for the ad group. For a description of the statuses, see the section Serving status for the ad group.
StateStateEnumState of the keyword or autotargeting. For a description of the states, see the section Status and state of a keyword.
ProductivityProductivity, nillableThis parameter is obsolete. Always returns null (nil).
StatisticsSearchStatistics

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.

StatisticsNetworkStatistics

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
ClickslongNumber of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days.
ImpressionslongNumber of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days.