get

Returns bids and priorities for keywords and autotargetings that match the specified criteria, along with auction data: bids and actual CPC for various traffic volumes in search results, and bids for various percents of audience coverage in ad networks.

  1. Restrictions
  2. Request
  3. Response

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": { /* params */
    "SelectionCriteria": { /* KeywordBidsSelectionCriteria */
      "CampaignIds": [(long), ... ],
      "AdGroupIds": [(long), ... ],
      "KeywordIds": [(long), ... ], 
      "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ]
    }, /* required */
    "FieldNames": [( "KeywordId" | "AdGroupId" | "CampaignId" | "ServingStatus" | "StrategyPriority" ), ... ], /* required */
    "SearchFieldNames": [( "Bid" | "AuctionBids" ), ... ],
    "NetworkFieldNames": [( "Bid" | "Coverage" ), ... ],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  } 
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / GetRequest (for SOAP)
SelectionCriteriaKeywordBidsSelectionCriteriaCriteria for selecting keywords and autotargetings.Yes
FieldNamesarray of KeywordBidFieldEnum

Names of top-level parameters to get.

Yes
SearchFieldNamesarray of KeywordBidSearchFieldEnum

Names of search bidding parameters to get.

Don't request the AuctionBids parameter if displays in search results are disabled for the campaign (the SERVING_OFF strategy in search).

No
NetworkFieldNamesarray of KeywordBidNetworkFieldEnum

Names of ad network bidding parameters to get.

Don't request the Coverage parameter if the campaign has displays in ad networks disabled (the SERVING_OFF strategy in ad networks).

No
PageLimitOffset

Structure that defines the page for paginated selection of data.

No
KeywordBidsSelectionCriteria structure
CampaignIdsarray of longGet bids or priorities for keywords and autotargetings in the specified campaigns. From 1 to 10 items in the array.One of the parameters KeywordIds, AdGroupIds, or CampaignIds (or all may be present)
AdGroupIdsarray of longGet bids or priorities for keywords and autotargetings in the specified ad groups. From 1 to 1000 items in the array.
KeywordIdsarray of longGet bids or priorities for the specified keywords and autotargetings. Maximum of 10,000 items in the array.
ServingStatusesarray 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 Serving status for the ad group.No

Response

Response structure in JSON format:

{
  "result": { /* result */
    "KeywordBids": [{  /* KeywordBidGetItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
      "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ), /* nillable */
      "Search": { /* Search */
        "Bid": (long),
        "AuctionBids": { /* AuctionBids */
          "AuctionBidItems": [{  /* AuctionBidItem */
            "TrafficVolume": (int), /* required */
            "Bid": (long), /* required */
            "Price": (long) /* required */
          }, ... ] 
        } /* nillable */
      },
      "Network": { /* Network */
        "Bid": (long),
        "Coverage": {  /* Coverage */
          "CoverageItems": [{ /* NetworkCoverageItem */
            "Probability": (decimal), /* required */
            "Bid": (long) /* required */
          }, ... ] 
        }  /* nillable */
      }
    }, ... ],
    "LimitedBy": (long)
  }
}
ParameterTypeDescription
Result structure (for JSON) / GetResponse (for SOAP)
KeywordBidsarray of KeywordBidGetItemBids and/or priorities.
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.
KeywordBidGetItem structure
CampaignIdlongID of the campaign that the keyword or autotargeting is associated with.
AdGroupIdlongID of the ad group that the keyword or autotargeting is associated with.
KeywordIdlongID of the keyword or autotargeting.
ServingStatusServingStatusEnumServing status for the ad group. For a description of the statuses, see the section Serving status for the ad group.
StrategyPriorityPriorityEnum, nillablePriority of the keyword or autotargeting: LOW, NORMAL or HIGH.
SearchSearchBid and auction data in search.
NetworkNetwork

Bid and auction data in ad networks.

BidlongThe bid for displays in search results that was set by the advertiser.
AuctionBidsAuctionBids, nillable

Bids and actual CPCs in search results for various traffic volumes for this keyword.

If the group only has image ads, it returns null (nil).

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 structure
AuctionBidItemsarray of AuctionBidItemArray of bids and actual CPCs in search results for various traffic volumes.
AuctionBidItem structure
TrafficVolumeintTraffic volume.
BidlongBid in search for the specified traffic volume.
PricelongThe actual CPC for the specified traffic volume.
Network structure
Bidlong

The bid for displays in ad networks that was set by the advertiser.

For autotargeting, this parameter isn't returned.

CoverageCoverage, nillableThe bids in ad networks that correspond to various percentages of audience coverage for this keyword.

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

Coverage structure
CoverageItemsNetworkCoverageItemArray of bids that correspond to various percentages of audience coverage.
NetworkCoverageItem structure
ProbabilitydecimalThe frequency of impressions (the audience coverage) in ad networks. Indicated as a percentage from 0 to 100.
BidlongBid in ad networks for the specified frequency.