Documentation

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.

Attention! All returned monetary values are whole integers — the result of multiplying the bid or price by 1,000,000.

Restrictions

The method returns a maximum of 10,000 objects.

Request

Request structure in JSON format:

{
  "method": "get",
  "params": { 
    "SelectionCriteria
[no-highlight[

Criteria for selecting keywords and autotargetings.

Required

Yes

]no-highlight]
": { /* BidsSelectionCriteria */ "KeywordIds
[no-highlight[

Get bids or priorities for the specified keywords and autotargetings. Maximum of 10,000 items in the array.

Required

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

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

Get bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array.

Required

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

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

Get bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array.

Required

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

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

Get bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For a description of the statuses, see the section Ad group serving status.

Required

No

]no-highlight]
": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ] }, /* required */ "FieldNames
[no-highlight[

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

Required

Yes

]no-highlight]
": [( "KeywordId" | ...
[no-highlight[

“KeywordId“ | “AdGroupId“ | “CampaignId“ | “ServingStatus“ | “Bid“ | “ContextBid“ | “StrategyPriority“ | “CompetitorsBids“ | “SearchPrices“ | “ContextCoverage“ | “MinSearchPrice“ | “CurrentSearchPrice“ | “AuctionBids“

]no-highlight]
| "AuctionBids" ), ... ], /* 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 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 longGet bids or priorities for the specified keywords and autotargetings. Maximum of 10,000 items in the array.One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present)
AdGroupIds array of longGet bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array.
CampaignIds array of longGet bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array.
ServingStatuses array of ServingStatusEnumGet bids or priorities for keywords and autotargetings with the specified ad group serving statuses. For a description of the statuses, see the section Ad group serving status.No

Response

Response structure in JSON format:

{
  "result": { 
    "Bids
[no-highlight[

Bids and/or priorities.

]no-highlight]
": [{ /* BidGetItem */ "CampaignId
[no-highlight[

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

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

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

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

ID of the keyword or autotargeting.

]no-highlight]
": (long), "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" ), "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 */ "CompetitorsBids
[no-highlight[

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.

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

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.

]no-highlight]
": [{ /* SearchPrices */ "Position
[no-highlight[

Display position in search results:

  • FOOTERBLOCK — Minimum bid for the 4th position in Guaranteed (for getting into Guaranteed Placement).
  • FOOTERFIRST — Minimum bid for the 1st position in Guaranteed.
  • PREMIUMBLOCK — Minimum bid for the 4th position in Premium Placement (for getting into Premium Placement).
  • PREMIUMFIRST — Minimum bid for the 1st position in Premium Placement.

]no-highlight]
": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" ), "Price
[no-highlight[

Minimum bid for the specified position.

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

Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Use 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).

For autotargeting, it returns null (nil).

]no-highlight]
": { /* ContextCoverage */ "Items
[no-highlight[

Bids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Use as a guide when selecting bids.

]no-highlight]
": [{ /* ContextCoverageItem */ "Probability
[no-highlight[

The frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100.

]no-highlight]
": (decimal), /* required */ "Price
[no-highlight[

Bid in ad networks that the specified frequency is forecast for.

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

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

]no-highlight]
": (long), /* nillable */ "CurrentSearchPrice
[no-highlight[

Current CPC in search results. This price may be deducted for click-throughs on the search results page (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).

]no-highlight]
": (long), /* nillable */ "AuctionBids
[no-highlight[

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.

]no-highlight]
": [{ /* AuctionBidItem */ "Position
[no-highlight[

Display position: Pmn, where

  • m is the block number (1 is Premium Placement, 2 is Guaranteed Placement).
  • n is the position number within the block.

For example, P12 is the 2nd position in Premium Placement, and P21 is the 1st position in Guaranteed Placement.

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

Minimum bid for the specified position.

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

Actual CPC for the specified position.

]no-highlight]
": (long) }, ... ] }, ... ], "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)
Bids array of BidGetItemBids and/or priorities.
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.
BidGetItem structure
CampaignId longID of the campaign that the keyword or autotargeting is associated with.
AdGroupId longID of the ad group that the keyword or autotargeting is associated with.
KeywordId longID of the keyword or autotargeting.
ServingStatus ServingStatusEnumServing status for the ad group. For a description of the statuses, see the section Ad group serving status.
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.
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). Use 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
[no-highlight[

Displays are disabled

]no-highlight]
or NETWORK_DEFAULT
[no-highlight[

The bid on the ad network is based on the bid on search

]no-highlight]
strategy in ad networks, it returns null (nil).

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 price may be deducted for click-throughs on the search results page (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 PositionEnumDisplay position in search results:
  • FOOTERBLOCK — Minimum bid for the 4th position in Guaranteed (for getting into Guaranteed Placement).
  • FOOTERFIRST — Minimum bid for the 1st position in Guaranteed.
  • PREMIUMBLOCK — Minimum bid for the 4th position in Premium Placement (for getting into Premium Placement).
  • PREMIUMFIRST — Minimum bid for the 1st position in Premium Placement.
Price longMinimum bid for the specified position.
ContextCoverage structure
Items array of ContextCoverageItemBids for this keyword that allow you to get various percentages of audience coverage in ad networks (forecast). Use as a guide when selecting bids.
ContextCoverageItem structure
Probability decimalThe frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100.
Price longBid in ad networks that the specified frequency is forecast for.
AuctionBidItem structure
Position stringDisplay position: Pmn, where
  • m is the block number (1 is Premium Placement, 2 is Guaranteed Placement).
  • n is the position number within the block.

For example, P12 is the 2nd position in Premium Placement, and P21 is the 1st position in Guaranteed Placement.

Bid longMinimum bid for the specified position.
Price longActual 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
      }
    ]
  }
}