get
Returns bids and priorities for keywords and autotargetings that match the specified criteria, along with data that is useful for bid selection: auction data on the search display positions and bids for various percents of audience coverage in ad networks.
You can get bids and priorities regardless of whether a manual or automatic strategy is selected in the campaign.
Restrictions
The method returns a maximum of 10,000 objects.
Request
Request structure in JSON format:
{
"method": "get",
"params": { /* params */
"SelectionCriteria": { /* BidsSelectionCriteria */
"KeywordIds": [(long), ... ],
"AdGroupIds": [(long), ... ],
"CampaignIds": [(long), ... ],
"ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ]
}, /* required */
"FieldNames": [( "KeywordId" | ... | "AuctionBids" ), ... ], /* required */
"Page": { /* LimitOffset */
"Limit": (long),
"Offset": (long)
}
}
}
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | BidsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of BidFieldEnum | Names of top-level parameters to get. Don't request the parameters CompetitorsBids, SearchPrices, MinSearchPrice, CurrentSearchPrice, and AuctionBids if the campaign has displays on search disabled (the SERVING_OFF strategy for search results). Don't request the ContextCoverage parameter if the campaign has displays in ad networks disabled (the SERVING_OFF strategy in ad networks). | Yes |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
BidsSelectionCriteria structure | |||
KeywordIds | array of long | Get bids or priorities for the specified keywords and autotargetings. A maximum of 10,000 items in the array. | One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Get bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array. | |
CampaignIds | array of long | Get bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array. | |
ServingStatuses | array of ServingStatusEnum | Get bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For status descriptions, see Ad group serving status. | No |
Parameter | Type | Description | Required |
Params structure (for JSON) / GetRequest (for SOAP) | |||
---|---|---|---|
SelectionCriteria | BidsSelectionCriteria | Criteria for selecting keywords and autotargetings. | Yes |
FieldNames | array of BidFieldEnum | Names of top-level parameters to get. Don't request the parameters CompetitorsBids, SearchPrices, MinSearchPrice, CurrentSearchPrice, and AuctionBids if the campaign has displays on search disabled (the SERVING_OFF strategy for search results). Don't request the ContextCoverage parameter if the campaign has displays in ad networks disabled (the SERVING_OFF strategy in ad networks). | Yes |
Page | LimitOffset | Structure that defines the page for paginated selection of data. | No |
BidsSelectionCriteria structure | |||
KeywordIds | array of long | Get bids or priorities for the specified keywords and autotargetings. A maximum of 10,000 items in the array. | One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present) |
AdGroupIds | array of long | Get bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array. | |
CampaignIds | array of long | Get bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array. | |
ServingStatuses | array of ServingStatusEnum | Get bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For status descriptions, see Ad group serving status. | No |
Response
Response structure in JSON format:
{
"result": { /* result */
"Bids": [{ /* BidGetItem */
"CampaignId": (long),
"AdGroupId": (long),
"KeywordId": (long),
"ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
"Bid": (long),
"AutotargetingSearchBidIsAuto" : ("YES"|"NO"),
"ContextBid": (long),
"StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */
"CompetitorsBids": [(long), ... ],
"SearchPrices": [{ /* SearchPrices */
"Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" ),
"Price": (long)
}, ... ],
"ContextCoverage": { /* ContextCoverage */
"Items": [{ /* ContextCoverageItem */
"Probability": (decimal), /* required */
"Price": (long) /* required */
}, ... ]
}, /* nillable */
"MinSearchPrice": (long), /* nillable */
"CurrentSearchPrice": (long), /* nillable */
"AuctionBids": [{ /* AuctionBidItem */
"Position": (string),
"Bid": (long),
"Price": (long)
}, ... ]
}, ... ],
"LimitedBy": (long)
}
}
Parameter | Type | Description |
Result structure (for JSON) / GetResponse (for SOAP) | ||
---|---|---|
Bids | array of BidGetItem | Bids and/or priorities. |
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. |
BidGetItem structure | ||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. |
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. |
KeywordId | long | ID of the keyword or autotargeting. |
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. |
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. |
CompetitorsBids | array of long | Array of minimum bids for this keyword for all positions in Premium Placement and Guaranteed Placement. 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. |
SearchPrices | array of SearchPrices | Minimum bids for this keyword for display positions in the search. 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. |
ContextCoverage | ContextCoverage, nillable | Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Used as a guide when selecting bids. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). If the campaign uses the SERVING_OFF or NETWORK_DEFAULT strategy in ad networks, it returns null (nil). Restriction. The NETWORK_DEFAULT parameter is not supported for the HIGHEST_POSITION manual strategy. For autotargeting, it returns null (nil). |
MinSearchPrice | long, nillable | The minimum bid set for the advertiser that allows displays in search results. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
CurrentSearchPrice | long, nillable | Current CPC in search results. This amount can be debited whenever your ad is clicked on a page showing search results for a query that exactly matches the keyword. For more information, see How is cost per click calculated? in the Help for Yandex.Direct. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
AuctionBids | array of AuctionBidItem | Auction results for the keyword. If the group only has image ads, this parameter is not returned. 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. |
SearchPrices structure | ||
Position | PositionEnum | Display position in search results:
|
Price | long | Minimum bid for the specified position. |
ContextCoverage structure | ||
Items | array of ContextCoverageItem | Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Used as a guide when selecting bids. |
ContextCoverageItem structure | ||
Probability | decimal | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. |
Price | long | Bid in ad networks that the specified frequency is forecast for. |
AuctionBidItem structure | ||
Position | string | Display position: Pmn, where
For example, P12 is the 2nd position in Premium Placement, and P21 is the 1st position in Guaranteed Placement. |
Bid | long | Minimum bid for the specified position. |
Price | long | Actual CPC for the specified position. |
Parameter | Type | Description |
Result structure (for JSON) / GetResponse (for SOAP) | ||
---|---|---|
Bids | array of BidGetItem | Bids and/or priorities. |
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. |
BidGetItem structure | ||
CampaignId | long | ID of the campaign that the keyword or autotargeting is associated with. |
AdGroupId | long | ID of the ad group that the keyword or autotargeting is associated with. |
KeywordId | long | ID of the keyword or autotargeting. |
ServingStatus | ServingStatusEnum | Serving status for the ad group. For status descriptions, see Ad group serving status. |
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. |
CompetitorsBids | array of long | Array of minimum bids for this keyword for all positions in Premium Placement and Guaranteed Placement. 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. |
SearchPrices | array of SearchPrices | Minimum bids for this keyword for display positions in the search. 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. |
ContextCoverage | ContextCoverage, nillable | Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Used as a guide when selecting bids. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). If the campaign uses the SERVING_OFF or NETWORK_DEFAULT strategy in ad networks, it returns null (nil). Restriction. The NETWORK_DEFAULT parameter is not supported for the HIGHEST_POSITION manual strategy. For autotargeting, it returns null (nil). |
MinSearchPrice | long, nillable | The minimum bid set for the advertiser that allows displays in search results. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
CurrentSearchPrice | long, nillable | Current CPC in search results. This amount can be debited whenever your ad is clicked on a page showing search results for a query that exactly matches the keyword. For more information, see How is cost per click calculated? in the Help for Yandex.Direct. If the ad group has very few displays (the ServingStatus parameter has the value RARELY_SERVED), it returns null (nil). For autotargeting, it returns null (nil). |
AuctionBids | array of AuctionBidItem | Auction results for the keyword. If the group only has image ads, this parameter is not returned. 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. |
SearchPrices structure | ||
Position | PositionEnum | Display position in search results:
|
Price | long | Minimum bid for the specified position. |
ContextCoverage structure | ||
Items | array of ContextCoverageItem | Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Used as a guide when selecting bids. |
ContextCoverageItem structure | ||
Probability | decimal | The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100. |
Price | long | Bid in ad networks that the specified frequency is forecast for. |
AuctionBidItem structure | ||
Position | string | Display position: Pmn, where
For example, P12 is the 2nd position in Premium Placement, and P21 is the 1st position in Guaranteed Placement. |
Bid | long | Minimum bid for the specified position. |
Price | long | Actual CPC for the specified position. |
Examples
- Request example
-
{ "method" : "get", "params" : { "SelectionCriteria" : { "KeywordIds" : [ 151289987, 151289988, 414808783, 414808784, 414808785, 414811825, 414811826, 414811827, 1574449505 ] }, "FieldNames" : [ "KeywordId", "Bid", "ContextBid" ] } }
- Response example
-
{ "result" : { "Bids" : [ { "KeywordId" : 414808783, "Bid" : 10000, "ContextBid" : 0 }, { "Bid" : 10000, "KeywordId" : 414808784, "ContextBid" : 0 }, { "Bid" : 10000, "KeywordId" : 414808785, "ContextBid" : 0 }, { "Bid" : 10000, "KeywordId" : 1574449505, "ContextBid" : 0 } ] } }