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 */
  } 
}
ParameterTypeDescriptionRequired
Params structure (for JSON) / SetAutoRequest structure (for SOAP)
KeywordBidsarray of KeywordBidSetAutoItemBid calculation parametersYes
KeywordBidSetAutoItem structure
CampaignIdlongThe campaign ID. Specified when updating the bid for all the campaign's keywords.Either CampaignId, AdGroupId, or KeywordId
AdGroupIdlongID of the ad group. Specified if the bid needs to be updated for all the group's keywords.
KeywordIdlong

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

Restriction. The autotargeting ID is not allowed.
BiddingRuleBiddingRule

Parameters for calculating bids.

Yes
BiddingRule structure
SearchByTrafficVolumeSearchByTrafficVolume

Parameters for calculating bids in search results.

Either SearchByTrafficVolume, or NetworkByCoverage
NetworkByCoverageNetworkByCoverage

Parameters for calculating bids in ad networks.

SearchByTrafficVolume structure
TargetTrafficVolumeint

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
IncreasePercentintMarkup percent from 0 to 1000. If omitted, markup is not calculated.No
BidCeilinglong

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
TargetCoverageint

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
IncreasePercentintMarkup percent from 0 to 1000. If omitted, markup is not calculated.No
BidCeilinglong

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) 
   }, ... ]
  }
}
ParameterTypeDescription
Result structure (for JSON) / SetAutoResponse structure (for SOAP)
SetAutoResultsarray of KeywordBidActionResultThe results of the bidding.
KeywordBidActionResult structure
CampaignIdlongThe campaign ID. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
AdGroupIdlongID 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).
KeywordIdlongKeyword ID. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
Warningsarray of ExceptionNotification

Warnings that occurred during the operation.

Errorsarray 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
      }
    ]
  }
}