REST Resource: customBiddingAlgorithms

  • A Custom Bidding Algorithm is a single resource used to create custom bidding strategies.

  • Custom bidding algorithms have a display name, an entity status to control usage, and a required immutable type (Script, Ads Data Hub, or Goal Builder based).

  • The algorithm's owner can be either a partner or an advertiser, and it can be shared with specific advertisers.

  • The modelReadiness field indicates the training and serving state of the custom bidding model for each accessing advertiser.

  • Custom bidding algorithms have a state (Enabled, Dormant, or Suspended) indicating whether they are actively scoring impressions.

Resource: CustomBiddingAlgorithm

A single custom bidding algorithm.

JSON representation 
{
  "name": string,
  "customBiddingAlgorithmId": string,
  "displayName": string,
  "entityStatus": enum (EntityStatus),
  "customBiddingAlgorithmType": enum (CustomBiddingAlgorithmType),
  "sharedAdvertiserIds": [
    string
  ],
  "modelReadiness": [
    {
      object (CustomBiddingModelReadinessState)
    }
  ],
  "customBiddingAlgorithmState": enum (State),

  // Union field owner can be only one of the following:
  "partnerId": string,
  "advertiserId": string
  // End of list of possible types for union field owner.
}
Fields
name

string

Output only. The resource name of the custom bidding algorithm.
customBiddingAlgorithmId

string (int64 format)

Output only. The unique ID of the custom bidding algorithm. Assigned by the system.
displayName

string

Required. The display name of the custom bidding algorithm.

Must be UTF-8 encoded with a maximum size of 240 bytes.
entityStatus

enum (EntityStatus)

Controls whether or not the custom bidding algorithm can be used as a bidding strategy.

Accepted values are:

  • ENTITY_STATUS_ACTIVE
  • ENTITY_STATUS_ARCHIVED
customBiddingAlgorithmType

enum (CustomBiddingAlgorithmType)

Required. Immutable. The type of custom bidding algorithm.
sharedAdvertiserIds[]

string (int64 format)

The IDs of the advertisers who have access to this algorithm. If advertiserId is set, this field will only consist of that value.

This field will not be set if the algorithm owner is a partner and is being retrieved using an advertiser accessor.
modelReadiness[]

object (CustomBiddingModelReadinessState)

Output only. The state of custom bidding model readiness for each advertiser who has access.

This field may only include the state of the queried advertiser if the algorithm owner is a partner and is being retrieved using an advertiser accessor.
customBiddingAlgorithmState

enum (State)

Output only. The status of custom bidding algorithm.
Union field owner. Identifies the DV360 entity that owns the custom bidding algorithm. It can be either a partner or an advertiser. owner can be only one of the following:
partnerId

string (int64 format)

Immutable. The unique ID of the partner that owns the custom bidding algorithm.
advertiserId

string (int64 format)

Immutable. The unique ID of the advertiser that owns the custom bidding algorithm.

CustomBiddingAlgorithmType

Possible types of custom bidding algorithms.

Enums
CUSTOM_BIDDING_ALGORITHM_TYPE_UNSPECIFIED Algorithm type is not specified or is unknown in this version.
SCRIPT_BASED Algorithm generated through customer-uploaded custom bidding script files.
ADS_DATA_HUB_BASED Algorithm created through Ads Data Hub product.
GOAL_BUILDER_BASED Algorithm created through goal builder in DV3 UI.

CustomBiddingModelReadinessState

The custom bidding algorithm model readiness state for a single shared advertiser.

JSON representation 
{
  "advertiserId": string,
  "readinessState": enum (ReadinessState)
}
Fields
advertiserId

string (int64 format)

The unique ID of the relevant advertiser.
readinessState

enum (ReadinessState)

The readiness state of custom bidding model.

ReadinessState

Possible states of model readiness.

Enums
READINESS_STATE_UNSPECIFIED State is not specified or is unknown in this version.
READINESS_STATE_ACTIVE The model is trained and ready for serving.
READINESS_STATE_INSUFFICIENT_DATA There is not enough data to train the serving model.
READINESS_STATE_TRAINING The model is training and not ready for serving.
READINESS_STATE_NO_VALID_SCRIPT A valid custom bidding script has not been provided with which to train the model. This state will only be applied to algorithms whose customBiddingAlgorithmType is SCRIPT_BASED.

State

Possible states of custom bidding algorithms.

Enums
STATE_UNSPECIFIED State is not specified or is unknown in this version.
ENABLED Algorithm is enabled, either recently used, currently used or scheduled to be used. The algorithm is actively scoring impressions.
DORMANT Algorithm has not been used recently. Although the algorithm still acts as ENABLED, it will eventually be suspended if not used.
SUSPENDED Algorithm is susepended from scoring impressions and doesn't have a serving model trained. If the algorithm is assigned to a line item or otherwise updated, it will switch back to the ENABLED state and require time to prepare the serving model again.

Methods

create

 Creates a new custom bidding algorithm.

get

 Gets a custom bidding algorithm.

list

 Lists custom bidding algorithms that are accessible to the current user and can be used in bidding stratgies.

patch

 Updates an existing custom bidding algorithm.

uploadScript

 Creates a custom bidding script reference object for a script file.