setAuto

The automatic bid constructor calculates bids for keywords based on the selected algorithm.

  1. Restrictions
  2. Request
  3. Response
  4. Examples

The method sets bids in asynchronous mode and does not return bids. Use the get method to get bids.

A bid can be set only if a manual strategy is selected in the campaign.

The method doesn't reset the automatic bid value (AutotargetingSearchBidIsAuto).

If an item in the input array contains bids that are not appropriate for the strategy, these bids are not applied.

  • If the campaign has an automatic strategy selected, an error is returned.
  • If displays in search results are disabled in the campaign and the Scope parameter has only the SEARCH parameter, an error is returned. If both values are passed (SEARCH and NETWORK), bids are only updated in ad networks and a warning is displayed.
  • If the campaign has a manual strategy in search results, an error is returned if this campaign doesn't have independent bid management in ad networks, or if displays are disabled in ad networks but the Scope parameter only has the NETWORK value. If both values are passed (SEARCH and NETWORK), bids are only updated in search results and a warning is displayed.
Attention.
  • Bids and prices are passed via the Yandex Direct API as integer numbers. The value passed is a bid or price multiplied by 1,000,000.

  • All bids and prices are shown in the advertiser's currency.

To set bids in search results, pass the value SEARCH in the Scope parameter.

The bid calculation uses the values passed in the Position, IncreasePercent, CalculateBy, and MaxBid parameters.

Position CalculateBy Bid calculation formula
FOOTERBLOCK VALUE

Minimum bid for 4th position in Guaranteed + minimum bid for 4th position in Guaranteed × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 4th position in Guaranteed + (minimum bid for 1st position – minimum bid for 4th position in Guaranteed) × IncreasePercent / 100,

but no greater than MaxBid

FOOTERFIRST VALUE

Minimum bid for 1st position in Guaranteed + minimum bid for 1st position in Guaranteed × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 1st position in Guaranteed + (minimum bid for 3rd position in Premium – minimum bid for 1st position in Guaranteed) × IncreasePercent / 100,

but no greater than MaxBid

PREMIUMBLOCK or P14 VALUE

Minimum bid for 4th position in Premium + minimum bid for 4th position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 4th position in Premium + (minimum bid for 3rd position in Premium – minimum bid for 4th position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

P13 VALUE

Minimum bid for 3rd position in Premium + minimum bid for 3rd position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 3rd position in Premium + (minimum bid for 2nd position in Premium – minimum bid for 3rd position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

P12 VALUE

Minimum bid for 2nd position in Premium + minimum bid for 2nd position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 2nd position in Premium + (minimum bid for 1st position in Premium – minimum bid for 2nd position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

PREMIUMFIRST or P11 VALUE

Minimum bid for 1st position in Premium + minimum bid for 1st position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 1st position in Premium, but no greater than MaxBid

Position CalculateBy Bid calculation formula
FOOTERBLOCK VALUE

Minimum bid for 4th position in Guaranteed + minimum bid for 4th position in Guaranteed × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 4th position in Guaranteed + (minimum bid for 1st position – minimum bid for 4th position in Guaranteed) × IncreasePercent / 100,

but no greater than MaxBid

FOOTERFIRST VALUE

Minimum bid for 1st position in Guaranteed + minimum bid for 1st position in Guaranteed × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 1st position in Guaranteed + (minimum bid for 3rd position in Premium – minimum bid for 1st position in Guaranteed) × IncreasePercent / 100,

but no greater than MaxBid

PREMIUMBLOCK or P14 VALUE

Minimum bid for 4th position in Premium + minimum bid for 4th position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 4th position in Premium + (minimum bid for 3rd position in Premium – minimum bid for 4th position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

P13 VALUE

Minimum bid for 3rd position in Premium + minimum bid for 3rd position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 3rd position in Premium + (minimum bid for 2nd position in Premium – minimum bid for 3rd position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

P12 VALUE

Minimum bid for 2nd position in Premium + minimum bid for 2nd position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 2nd position in Premium + (minimum bid for 1st position in Premium – minimum bid for 2nd position in Premium) × IncreasePercent / 100,

but no greater than MaxBid

PREMIUMFIRST or P11 VALUE

Minimum bid for 1st position in Premium + minimum bid for 1st position in Premium × IncreasePercent / 100,

but no greater than MaxBid

DIFF

Minimum bid for 1st position in Premium, but no greater than MaxBid

Note. Over time, competitors' activity might increase the minimum bid for a position, and it will be higher than the advertiser's bid. The higher the markup, the more likely it is that the ad will be shown in the selected position, but expenses are also greater.

Restrictions

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.

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 */
    "Bids": [{  /* BidSetAutoItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "MaxBid": (long),
      "Position": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" | "P21" | "P22" | "P23" | "P24" ),
      "IncreasePercent": (int),
      "CalculateBy": ( "VALUE" | "DIFF" ),
      "ContextCoverage": (int),
      "Scope": [( "SEARCH" | "NETWORK" ), ... ] /* required */
    }, ... ] /* required */
  } 
}
Parameter Type Description Required
Params structure (for JSON) / SetAutoRequest structure (for SOAP)
Bids array of BidSetAutoItem Bid calculation parameters Yes
BidSetAutoItem 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 when 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.
Scope array of ScopeEnum Specifies which bids to set. The array may contain the following elements (one or both): Yes
MaxBid long

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

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

No
Position PositionEnum

The display position whose bid is used as the basis for calculating bids in search results.

A markup is added to the bid for the selected position (see the IncreasePercent and CalculateBy parameters).

If the Scope array has the Search value
IncreasePercent int Markup percent from 0 to 1000. If omitted, markup is not calculated. No
CalculateBy CalculateByEnum

The base for calculating the markup:

  • VALUE — Price of the position specified in Position.

  • DIFF — The difference between the minimum bid for the position specified in the Position parameter and the for the next position.

    When the PREMIUMFIRST (P11) position is selected, there is no next position, and the markup is zero. This is also true when the FOOTERFIRST (P21) position is selected, if the price of the next PREMIUMBLOCK (P14) position is less (rare but possible).

If the Scope array has the Search value and the IncreasePercent parameter is set
ContextCoverage int

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

A markup is added to the bid that is needed to get the selected audience coverage (see the IncreasePercent parameter).

If the Scope array has the Network value
Parameter Type Description Required
Params structure (for JSON) / SetAutoRequest structure (for SOAP)
Bids array of BidSetAutoItem Bid calculation parameters Yes
BidSetAutoItem 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 when 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.
Scope array of ScopeEnum Specifies which bids to set. The array may contain the following elements (one or both): Yes
MaxBid long

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

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

No
Position PositionEnum

The display position whose bid is used as the basis for calculating bids in search results.

A markup is added to the bid for the selected position (see the IncreasePercent and CalculateBy parameters).

If the Scope array has the Search value
IncreasePercent int Markup percent from 0 to 1000. If omitted, markup is not calculated. No
CalculateBy CalculateByEnum

The base for calculating the markup:

  • VALUE — Price of the position specified in Position.

  • DIFF — The difference between the minimum bid for the position specified in the Position parameter and the for the next position.

    When the PREMIUMFIRST (P11) position is selected, there is no next position, and the markup is zero. This is also true when the FOOTERFIRST (P21) position is selected, if the price of the next PREMIUMBLOCK (P14) position is less (rare but possible).

If the Scope array has the Search value and the IncreasePercent parameter is set
ContextCoverage int

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

A markup is added to the bid that is needed to get the selected audience coverage (see the IncreasePercent parameter).

If the Scope array has the Network value
Attention. The CampaignId, AdGroupId and KeywordId parameters are mutually exclusive. A single request may only contain one of these parameters.

Response

Response structure in JSON format:

{
  "result": { /* result */
    "SetAutoResults": [{  /* BidActionResult */
      "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 BidActionResult Results of setting bids and/or priorities.
BidActionResult structure
CampaignId long The campaign ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
AdGroupId long ID of the ad group. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
KeywordId long Keyword ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.

Parameter Type Description
Result structure (for JSON) / SetAutoResponse structure (for SOAP)
SetAutoResults array of BidActionResult Results of setting bids and/or priorities.
BidActionResult structure
CampaignId long The campaign ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
AdGroupId long ID of the ad group. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
KeywordId long Keyword ID. Returned if there aren't any errors, if it was specified in the request. See Operations on object arrays.
Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example

Set the price in search results of the 1st position in Guaranteed + 50% of the difference from Premium, but no greater than 0.25.

{
  "method" : "setAuto",
  "params" : {
    "Bids" : [
      {
        "Scope" : [
          "SEARCH"
        ],
        "IncreasePercent" : 50,
        "CalculateBy" : "DIFF",
        "Position" : "FOOTERFIRST",
        "KeywordId" : 1574449505,
        "MaxBid" : 250000
      }
    ]
  }
}
Response example
{
  "result" : {
    "SetAutoResults" : [
      {
        "KeywordId" : 1574449505
      }
    ]
  }
}