Documentation

get

Returns parameters of keywords or autotargetings that match the set criteria: the values of substitution variables, status and state, productivity, statistics for impressions and clicks, and bids and priorities.
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": {  
    "SelectionCriteria
[no-highlight[

Criteria for selecting keywords and autotargetings.

Required

Yes

]no-highlight]
": { /* KeywordsSelectionCriteria */ "Ids
[no-highlight[

Selects keywords and autotargetings with the specified IDs. From 1 to 10,000 items in the array.

Required

One of the parameters Ids, AdGroupIds, or CampaignIds (or all may be present)

]no-highlight]
": [(long), ... ], "AdGroupIds
[no-highlight[

Selects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array.

Required

One of the parameters Ids, AdGroupIds, or CampaignIds (or all may be present)

]no-highlight]
": [(long), ... ], "CampaignIds
[no-highlight[

Selects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array.

Required

One of the parameters Ids, AdGroupIds, or CampaignIds (or all may be present)

]no-highlight]
": [(long), ... ], "States
[no-highlight[

Selects keywords and autotargetings with the specified states. See Status and state of a keyword.

Required

No

]no-highlight]
": [( "OFF" | "ON" | "SUSPENDED" ), ... ], "Statuses
[no-highlight[

Selects keywords and autotargetings with the specified statuses. See Status and state of a keyword.

Required

No

]no-highlight]
": [( "ACCEPTED" | "DRAFT" | "REJECTED"), ... ], "ServingStatuses
[no-highlight[

Selects keywords and autotargetings with the specified ad group serving statuses. See Ad group serving status.

Required

No

]no-highlight]
": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ], "ModifiedSince
[no-highlight[

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.

Required

No

]no-highlight]
": (string) }, /* required */ "FieldNames
[no-highlight[

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.

Required

Yes

]no-highlight]
": [( "Id" | "Keyword" | "State" | "Status" | "ServingStatus" | "AdGroupId" | "CampaignId" | "Bid" | "ContextBid" | "StrategyPriority" | "UserParam1" | "UserParam2" | "Productivity" | "StatisticsSearch" | "StatisticsNetwork" ), ... ], /* required */ "Page
[no-highlight[

Structure that defines the page for paginated selection of data.

Required

No

]no-highlight]
": { /* 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 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)
AdGroupIds array of longSelects keywords and autotargetings from the specified groups. From 1 to 1000 items in the array.
CampaignIds array of longSelects keywords and autotargetings from the specified campaigns. From 1 to 10 items in the array.
States array of KeywordStatusSelectionEnumSelects keywords and autotargetings with the specified states. See Status and state of a keyword.No
Statuses array of StatusEnumSelects keywords and autotargetings with the specified statuses. See Status and state of a keyword.No
ServingStatuses array of ServingStatusEnumSelects 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 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": { 
    "Keywords
[no-highlight[

Keywords and autotargetings.

]no-highlight]
": [{ /* KeywordGetItem */ "Id
[no-highlight[

ID of the keyword or autotargeting.

]no-highlight]
": (long), "Keyword
[no-highlight[

Keywords. May contain negative keywords.

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

]no-highlight]
": (string), "AdGroupId
[no-highlight[

ID of the ad group that the keyword or autotargeting is associated with.

]no-highlight]
": (long), "CampaignId
[no-highlight[

ID of the campaign that the keyword or autotargeting is associated with.

]no-highlight]
": (long), "UserParam1
[no-highlight[

Value of the {param1}substitution variable. Maximum of 255 characters.

]no-highlight]
": (string), /* nillable */ "UserParam2
[no-highlight[

Value of the {param2}substitution variable. Maximum of 255 characters.

]no-highlight]
": (string), /* nillable */ "Bid
[no-highlight[

Bid in search results.

]no-highlight]
": (long), "ContextBid
[no-highlight[

Bid in ad networks.

For autotargeting, this parameter isn‘t returned.

]no-highlight]
": (long), "StrategyPriority
[no-highlight[

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

]no-highlight]
": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */ "State
[no-highlight[

State of the keyword or autotargeting. For a description of the states, see the section Status and state of a keyword.

]no-highlight]
": ( "OFF" | "ON" | "SUSPENDED" ), "Status
[no-highlight[

Status of the keyword or autotargeting. For a description of the statuses, see the section Status and state of a keyword.

]no-highlight]
": ( "ACCEPTED" | "DRAFT" | "REJECTED" | "UNKNOWN" ), "ServingStatus
[no-highlight[

Serving status for the ad group. For a description of the statuses, see the section Ad group serving status.

]no-highlight]
": ( "ELIGIBLE" | "RARELY_SERVED" ), "Productivity
[no-highlight[

Keyword productivity and recommendations for improvement.

For autotargeting, it returns null (nil).

]no-highlight]
": { /* Productivity */ "Value
[no-highlight[

Productivity value for the keyword (to the first decimal place).

]no-highlight]
": (decimal), "References
[no-highlight[

Array of numbers of recommendations for this keyword.

To get the list of recommendations, use the Dictionariesget method.

]no-highlight]
": [(int), ... ] }, /* nillable */ "StatisticsSearch
[no-highlight[

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.

]no-highlight]
": { /* Statistics */ "Clicks
[no-highlight[

Number of clicks on all the group‘s ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad.

]no-highlight]
": (long), /* required */ "Impressions
[no-highlight[

Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword.

]no-highlight]
": (long) /* required */ }, "StatisticsNetwork
[no-highlight[

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.

]no-highlight]
": { /* Statistics */ "Clicks
[no-highlight[

Number of clicks on all the group‘s ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad.

]no-highlight]
": (long), /* required */ "Impressions
[no-highlight[

Number of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword.

]no-highlight]
": (long) /* required */ } }, ... ], "LimitedBy
[no-highlight[

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

]no-highlight]
": (long) } }
Parameter Type Description
result structure (for JSON) / GetResponse (for SOAP)
Keywords array of KeywordGetItemKeywords and autotargetings.
LimitedBy longSequential 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 selection.
KeywordGetItem structure
Id longID of the keyword or autotargeting.
AdGroupId longID of the ad group that the keyword or autotargeting is associated with.
CampaignId longID 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, nillableValue of the {param1} substitution variable. Maximum of 255 characters.
UserParam2 string, nillableValue of the {param2} substitution variable. Maximum of 255 characters.
Bid longBid in search results.
ContextBid long

Bid in ad networks.

For autotargeting, this parameter isn't returned.

StrategyPriority PriorityEnum, nillablePriority of the keyword or autotargeting: LOW, NORMAL or HIGH.
Status StatusEnumStatus of the keyword or autotargeting. For a description of the statuses, see the section Status and state of a keyword.
ServingStatus ServingStatusEnumServing status for the ad group. For a description of the statuses, see the section Ad group serving status.
State StateEnumState of the keyword or autotargeting. For a description of the states, see the section Status and state of a keyword.
Productivity Productivity, nillable

Keyword productivity and recommendations for improvement.

For autotargeting, it 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.

Productivity structure
Value decimalProductivity value for the keyword (to the first decimal place).
References array of int

Array of numbers of recommendations for this keyword.

To get the list of recommendations, use the Dictionaries
[no-highlight[

This service is for getting reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, and other information.

More Dictionaries

]no-highlight]
get
[no-highlight[

Returns reference data: regions, time zones, currency exchange rates, metro stations, restrictions on parameter values, ad exchanges (SSPs), and other information.

More get

]no-highlight]
method.
Statistics structure
Clicks longNumber of clicks on all the group's ads that were shown for this keyword or autotargeting. Calculated for the last 28 days. The calculation uses those days during which there was at least one click on an ad.
Impressions longNumber of impressions for this keyword or autotargeting for all ads in the ad group. Calculated for the last 28 days. The calculation uses those days during which there was at least one ad impression for this keyword.