setAuto

Sets bids for keywords on search depending on the desired traffic volume, or bids in ad networks depending on the desired frequency of impressions (audience share).

Bid calculation formula:

Bid that corresponds to TargetTrafficVolume × (1 + IncreasePercent / 100),

but no more than BidCeiling.

Over time, competitors' activity might increase the bid for a certain traffic volume, and it will go higher than the advertiser's bid. The higher the markup, the higher the traffic volume, but spending also increases.

The method does not return the assigned bids, but you can get them using the get method.

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 bid for search can be set only if the HIGHEST_POSITION strategy is selected in the campaign for displays in search results. Otherwise, an error is returned.

The bid in ad networks can be assigned only if the MAXIMUM_COVERAGE or MANUAL_CPM strategy is selected in the campaign for displays in ad networks. Otherwise, an error is returned.

A single request can only set bids for the same type of objects — either for campaigns only, or for groups only, or for keywords only.

The method doesn't support setting the bid for autotargeting separately. Changing bids in search for all the keywords in an ad group or campaign may affect the autotargeting bid.

Maximum number of objects per method call:
  • campaigns — maximum of 10
  • groups — maximum of 1000
  • keywords — maximum of 10,000

Request

Request structure in JSON format:

{
  "method": "setAuto",
  "params": { /* params */
    "KeywordBids": [{  /* KeywordBidSetAutoItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "BiddingRule": { /* BiddingRule */
        "SearchByTrafficVolume": { /* SearchByTrafficVolume */
          "TargetTrafficVolume": (int), /* required */
          "IncreasePercent": (int),
          "BidCeiling": (long)
        },
        "NetworkByCoverage": { /* NetworkByCoverage */
          "TargetCoverage": (int), /* required */
          "IncreasePercent": (int),
          "BidCeiling": (long)
        }
      } /* required */
    }, ... ] /* required */
  } 
}
Parameter Type Description Required
Params structure (for JSON) / SetAutoRequest structure (for SOAP)
KeywordBids array of KeywordBidSetAutoItem Bid calculation parameters Yes
KeywordBidSetAutoItem structure
CampaignId long The campaign ID. Specified when updating the bid for all the campaign's keywords. Either CampaignId, AdGroupId, or KeywordId
AdGroupId long ID of the ad group. Specified if the bid needs to be updated for all the group's keywords.
KeywordId long

The keyword ID. Specified when updating the bid for an individual keyword.

Restriction. The autotargeting ID is not allowed.
BiddingRule BiddingRule

Parameters for calculating bids.

Yes
BiddingRule structure
SearchByTrafficVolume SearchByTrafficVolume

Parameters for calculating bids in search results.

Either SearchByTrafficVolume, or NetworkByCoverage
NetworkByCoverage NetworkByCoverage

Parameters for calculating bids in ad networks.

SearchByTrafficVolume structure
TargetTrafficVolume int

The desired traffic volume in search results. Indicated as a percentage from 5 to 100.

A markup is added to the bid that corresponds to the selected traffic volume (see the IncreasePercent parameter).

Yes
IncreasePercent int Markup percent from 0 to 1000. If omitted, markup is not calculated. No
BidCeiling long

Limit on the bid, multiplied by 1,000,000. Integer.

Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request.

No
NetworkByCoverage structure
TargetCoverage int

The desired frequency of impressions (the audience coverage) in ad networks. Specified as a percent from 1 to 100.

A markup is added to the bid that corresponds to the selected impression frequency (see the IncreasePercent parameter).

Yes
IncreasePercent int Markup percent from 0 to 1000. If omitted, markup is not calculated. No
BidCeiling long

Limit on the bid, multiplied by 1,000,000. Integer.

Specified in the advertiser's currency. Restrictions are listed in the currency reference. To get it, use the Dictionaries.get method and specify the Currencies dictionary name in the request.

No
Attention. The CampaignId, AdGroupId and KeywordId parameters are mutually exclusive. A single request can only contain one of these parameters.

Response

Response structure in JSON format:

{
  "result": { /* result */
    "SetAutoResults": [{  /* KeywordBidActionResult */
      "Warnings": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
      }, ... ],
      "Errors": [{  /* ExceptionNotification */
        "Code": (int), /* required */
        "Message": (string), /* required */
        "Details": (string)
     }, ... ],        
    "CampaignId": (long),
    "AdGroupId": (long),
    "KeywordId": (long) 
   }, ... ]
  }
}
Parameter Type Description
Result structure (for JSON) / SetAutoResponse structure (for SOAP)
SetAutoResults array of KeywordBidActionResult The results of the bidding.
KeywordBidActionResult structure
CampaignId long The campaign ID. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
AdGroupId long ID of the ad group. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
KeywordId long Keyword ID. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example

Sets the bid in search for all keywords in an ad group to get the traffic volume of 75, increased by 10%, but not more than 12.

{
  "method": "setAuto",
  "params": {
    "KeywordBids": [{
      "AdGroupId": 636056397,
      "BiddingRule": {
        "SearchByTrafficVolume": {
          "TargetTrafficVolume": 75,
          "IncreasePercent": 10,
          "BidCeiling": 12000000,
        }
      }
    }] 
  }
} 
Response example
{
  "result" : {
    "SetAutoResults" : [
      {
        "AdGroupId" : 636056397
      }
    ]
  }
}