Documentation

setAuto

The automatic bid constructor calculates bids for keywords based on the selected algorithm.
The method sets bids in asynchronous mode and does not return bids. Use the get
[no-highlight[

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.

More get

]no-highlight]
method to get bids.

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

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 two values are passed (SEARCH and NETWORK), bids are updated only in ad networks, and a warning is issued.
  • 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 two values are passed (SEARCH and NETWORK), bids are updated only in search results, and a warning is issued.
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.

To set bids in search results, pass the value SEARCH in the Scope
[no-highlight[

Specifies which bids to set. The array may contain the following elements (one or both):

Required

Yes

]no-highlight]
parameter.
The bid calculation uses the values passed in the Position
[no-highlight[

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

Required

If the Scope array has the Search value

]no-highlight]
, IncreasePercent
[no-highlight[

Markup percent from 0 to 1000. If omitted, markup is not calculated.

Required

No

]no-highlight]
, CalculateBy
[no-highlight[

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 (this is an unusual situation, but possible).

Required

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

]no-highlight]
, and MaxBid
[no-highlight[

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

Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

Required

No

]no-highlight]
parameters.
PositionCalculateByBid calculation formula
FOOTERBLOCKVALUE

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

FOOTERFIRSTVALUE

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 P14VALUE

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

P13VALUE

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

P12VALUE

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 P11VALUE

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.

You can only set the bid in ad networks for strategies that allow separate management of bids in search results and ad networks.

To set bids in ad networks, pass the value NETWORK in the Scope
[no-highlight[

Specifies which bids to set. The array may contain the following elements (one or both):

Required

Yes

]no-highlight]
parameter.
Bid calculation uses the values passed in the parameters ContextCoverage
[no-highlight[

The 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 is needed to get the selected audience coverage (see the IncreasePercent parameter).

Required

If the Scope array has the Network value

]no-highlight]
, IncreasePercent
[no-highlight[

Markup percent from 0 to 1000. If omitted, markup is not calculated.

Required

No

]no-highlight]
, and MaxBid
[no-highlight[

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

Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

Required

No

]no-highlight]
.

Bid calculation formula:

Bid predicted to produce the specified impression frequency + bid predicted to produce the specified impression frequency × IncreasePercent / 100,

but not more than MaxBid.

Note. Bid calculation is based on probability, and does not guarantee the desired audience coverage.

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": { 
    "Bids
[no-highlight[

Bid calculation parameters

Required

Yes

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

The campaign ID. Specified when updating the bid for all the campaign‘s keywords.

Required

Either CampaignId, AdGroupId, or KeywordId

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

ID of the ad group. Specified if the bid needs to be updated for all the group‘s keywords.

Required

Either CampaignId, AdGroupId, or KeywordId

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

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

Restriction. The autotargeting ID is not allowed.

Required

Either CampaignId, AdGroupId, or KeywordId

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

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

Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

Required

No

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

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

Required

If the Scope array has the Search value

]no-highlight]
": ( "PREMIUMFIRST" | "PREMIUMBLOCK" | "FOOTERFIRST" | "FOOTERBLOCK" | "P11" | "P12" | "P13" | "P14" | "P21" | "P22" | "P23" | "P24" ), "IncreasePercent
[no-highlight[

Markup percent from 0 to 1000. If omitted, markup is not calculated.

Required

No

]no-highlight]
": (int), "CalculateBy
[no-highlight[

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 (this is an unusual situation, but possible).

Required

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

]no-highlight]
": ( "VALUE" | "DIFF" ), "ContextCoverage
[no-highlight[

The 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 is needed to get the selected audience coverage (see the IncreasePercent parameter).

Required

If the Scope array has the Network value

]no-highlight]
": (int), "Scope
[no-highlight[

Specifies which bids to set. The array may contain the following elements (one or both):

Required

Yes

]no-highlight]
": [( "SEARCH" | "NETWORK" ), ... ] /* required */ }, ... ] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / SetAutoRequest structure (for SOAP)
Bids array of BidSetAutoItemBid calculation parametersYes
BidSetAutoItem structure
CampaignId longThe campaign ID. Specified when updating the bid for all the campaign's keywords.Either CampaignId, AdGroupId, or KeywordId
AdGroupId longID 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.
Scope array of ScopeEnumSpecifies which bids to set. The array may contain the following elements (one or both):
  • SEARCH — Set bids in search results (Bid). Bid calculation uses the values passed in the parameters Position
    [no-highlight[

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

    Required

    If the Scope array has the Search value

    ]no-highlight]
    , IncreasePercent
    [no-highlight[

    Markup percent from 0 to 1000. If omitted, markup is not calculated.

    Required

    No

    ]no-highlight]
    , CalculateBy
    [no-highlight[

    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 (this is an unusual situation, but possible).

    Required

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

    ]no-highlight]
    , and MaxBid
    [no-highlight[

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

    Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

    Required

    No

    ]no-highlight]
    .
  • NETWORK — Set bids in ad networks (ContextBid). Bid calculation uses the values passed in the parameters ContextCoverage
    [no-highlight[

    The 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 is needed to get the selected audience coverage (see the IncreasePercent parameter).

    Required

    If the Scope array has the Network value

    ]no-highlight]
    , IncreasePercent
    [no-highlight[

    Markup percent from 0 to 1000. If omitted, markup is not calculated.

    Required

    No

    ]no-highlight]
    , and MaxBid
    [no-highlight[

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

    Specified in the advertiser‘s currency. For restrictions, see the page Minimum and maximum CPC.

    Required

    No

    ]no-highlight]
    .
Yes
MaxBid long

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

Specified in the advertiser's currency. For restrictions, see the page Minimum and maximum CPC.

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 intMarkup 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 (this is an unusual situation, 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. Specified as a percent from 1 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 can only contain one of these parameters.

Response

Response structure in JSON format:

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

Results of setting bids and/or priorities.

]no-highlight]
": [{ /* BidActionResult */ "Warnings
[no-highlight[

Warnings that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors
[no-highlight[

Errors that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "CampaignId
[no-highlight[

The campaign ID. Returned if there aren‘t any errors. See the section Operations on object arrays (if it was specified in the request).

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

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

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

Keyword ID. Returned if there aren‘t any errors. See the section Operations on object arrays (if it was specified in the request).

]no-highlight]
": (long) }, ... ] } }
Parameter Type Description
result structure (for JSON) / SetAutoResponse structure (for SOAP)
SetAutoResults array of BidActionResultResults of setting bids and/or priorities.
BidActionResult structure
CampaignId longThe campaign ID. Returned if there aren't any errors. See the section Operations on object arrays (if it was specified in the request).
AdGroupId longID 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 longKeyword 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

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