set

Sets fixed bids and priorities for keywords and autotargetings.

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

In 2023, we are going to disable manual bid management in YAN. Follow our news.

You can set the bid or priority for:

  • A separate keyword or autotargeting.

  • All keywords and autotargetings in an ad group.

  • All keywords and autotargetings in a campaign.

The bid or priority can be assigned according to which display strategy is selected in the campaign:

  • If the HIGHEST_POSITION display strategy is chosen for search, the SearchBid parameter can be specified.
  • If the MAXIMUM_COVERAGE or MANUAL_CPM display strategy is chosen for ad networks, the NetworkBid parameter can be specified.
  • If an automatic strategy is selected, you can use the StrategyPriority parameter: keywords with higher priority are allocated more traffic when possible, and they are the last ones to be stopped when budget funds are low.

If an item in the input array contains parameters that are not appropriate for the strategy, the values of these parameters are not changed.

  • If an item in the input array simultaneously contains both appropriate and inappropriate parameters for the strategy (for example, both a bid and a priority), the operation only changes the values of the parameters that correspond to the strategy, and a warning is returned.
  • If an item in the input array contains only parameters that are not appropriate for the strategy (for example, it contains only priority for a manual strategy), the operation is not executed, and an error is returned.
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.

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 and autotargetings only.

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

Request

Request structure in JSON format:

{
  "method": "set",
  "params": { /* params */
    "Bids": [{  /* BidSetItem */
      "CampaignId": (long),
      "AdGroupId": (long),
      "KeywordId": (long),
      "Bid": (long),
      "AutotargetingSearchBidIsAuto" : ("YES"|"NO"),
      "ContextBid": (long),
      "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ) 
    }, ... ] /* required */
  } 
}
Parameter Type Description Required
Params structure (for JSON) / SetRequest structure (for SOAP)
Bids array of BidSetItem Bids and/or priorities. Yes
BidSetItem structure
CampaignId long The campaign ID. Specified when setting the same bid or priority for all the keywords and autotargetings in a campaign. Either CampaignId, AdGroupId, or KeywordId
AdGroupId long ID of the ad group. Specified when setting the same bid or priority for all the keywords and autotargetings in a group.
KeywordId long The keyword ID. Specified when setting a bid or priority for an individual keyword or autotargeting.
Bid long

The bid on search, multiplied by 1,000,000. Integer. Only for manual strategies.

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.

At least one of the Bid, ContextBid, StrategyPriority, or AutotargetingSearchBidIsAuto parameters
AutotargetingSearchBidIsAuto YesNoEnum

A flag indicating whether automatic bid is enabled.

You can specify both a manual bid (Bid) and enable automatic bid (AutotargetingSearchBidIsAuto). In that case, automatic bid will be used, and manual bid will be applied if automatic bid is disabled.

If a manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to NO unless a different automatic bid value is delivered explicitly.

If no manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to YES unless a different automatic bid value is delivered explicitly.

ContextBid long

The bid in ad networks, multiplied by 1,000,000. Integer. Only for manual strategies with independent bid management in ad networks.

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.

Attention. An image ad can be displayed only if the bid is at least as high as the minimum bid for an ad with an image.
StrategyPriority PriorityEnum

Priority of the keyword: LOW, NORMAL or HIGH. Only for automatic strategies.

Parameter Type Description Required
Params structure (for JSON) / SetRequest structure (for SOAP)
Bids array of BidSetItem Bids and/or priorities. Yes
BidSetItem structure
CampaignId long The campaign ID. Specified when setting the same bid or priority for all the keywords and autotargetings in a campaign. Either CampaignId, AdGroupId, or KeywordId
AdGroupId long ID of the ad group. Specified when setting the same bid or priority for all the keywords and autotargetings in a group.
KeywordId long The keyword ID. Specified when setting a bid or priority for an individual keyword or autotargeting.
Bid long

The bid on search, multiplied by 1,000,000. Integer. Only for manual strategies.

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.

At least one of the Bid, ContextBid, StrategyPriority, or AutotargetingSearchBidIsAuto parameters
AutotargetingSearchBidIsAuto YesNoEnum

A flag indicating whether automatic bid is enabled.

You can specify both a manual bid (Bid) and enable automatic bid (AutotargetingSearchBidIsAuto). In that case, automatic bid will be used, and manual bid will be applied if automatic bid is disabled.

If a manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to NO unless a different automatic bid value is delivered explicitly.

If no manual bid (Bid) is specified: the automatic bid value (AutotargetingSearchBidIsAuto) is set to YES unless a different automatic bid value is delivered explicitly.

ContextBid long

The bid in ad networks, multiplied by 1,000,000. Integer. Only for manual strategies with independent bid management in ad networks.

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.

Attention. An image ad can be displayed only if the bid is at least as high as the minimum bid for an ad with an image.
StrategyPriority PriorityEnum

Priority of the keyword: LOW, NORMAL or HIGH. Only for automatic strategies.

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 */
    "SetResults": [{  /* 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) / SetResponse structure (for SOAP)
SetResults 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 ID of the keyword or autotargeting. 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) / SetResponse structure (for SOAP)
SetResults 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 ID of the keyword or autotargeting. 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
{
  "method" : "set",
  "params" : {
    "Bids" : [
      {
        "StrategyPriority" : "HIGH",
        "CampaignId" : 4193065
      },
      {
        "Bid" : 14000,
        "CampaignId" : 7273721
      }
    ]
  }
}
Response example
{
  "result" : {
    "SetResults" : [
      {
        "CampaignId" : 4193065
      },
      {
        "CampaignId" : 7273721
      }
    ]
  }
}