Page tree

Skip to end of metadata
Go to start of metadata

Custom Models

This offering is currently in Alpha and available to a limited set of clients. For more information about custom models and potential use cases that may apply to your business, reach out to your account representative.

Xandr's API empowers you to create your own custom predictive models (previously known as "AppNexus Programmable Bidder" or "APB") and upload them directly to our open platform. You can:

  • Have your data scientists write predictive models in Bonsai, a high-level domain-specific language (DSL) that's very similar to the popular Python language
  • Validate and upload your models via our API and assign them to campaigns via our API or UI
  • Run your models on our bidders and benefit from our infrastructure's speed, scale, reliability, and lower costs

This page helps you get started. 

On This Page

Custom Model Types

Currently, it's possible to create two types of custom predictive models:

Bid Price

The Bid Price model uses a decision tree to determine a campaign's CPM bid. This type of model serves as a campaign's third-party buying strategy, in place of standard CPM strategies like "Bid a Base CPM" or "Optimize to a % Margin".

Bid Modifier

The Bid Modifier model uses a decision tree to adjust a campaign's optimization-derived CPM bid up or down. This type of model is used in conjunction with a buying strategy that uses Xandr's optimization, like "Optimize to a predicted CPA goal" or "Optimize to a predicted CPC goal".

The bids calculated by the model are always expressed in the currency set on the advertiser, even if you have specified a different currency for the line item or campaign.


The Alpha workflow requires using the API. Alpha clients are expected to have completed our API Onboarding Process before getting started.

Step 1. Identify Your Requirements

You will write your custom model as a decision tree, where branches of the tree express conditions that lead to specific outputs (bid prices in the case of a Bid Price Model and bid multipliers in the case of a Bid Modifier Model). The conditions can be based on a set of Bonsai features and feature values. Before writing your tree:

  • Take a close look at the Bonsai Features that are available.
  • Sketch how you want to use tree features to determine outputs.
  • Be sure to take advantage of reporting data in identifying the right features and values. For more information, see Log Level Data Feeds and "Standard Reporting" in the UI documentation (customer login required).

Example: Decision tree for bid pricing

Use custom models for pricing, not targeting

Use custom models to determine how to price impressions, not how to target them. For targeting impressions, you should continue to use the Targeting section of campaign setup in the UI or the Profile Service for targeting via the API.

Step 2. Create Your Decision Tree

Once you know the features and steps you want to follow to price or modify bids for a campaign, write them as a decision tree in our Bonsai Language. Use the examples on that page as well as the simple example below to jumpstart your understanding of how to write your tree.

Use tabs for indentation, not spaces

In Bonsai, indentation is used to group expressions (similar to Python). Be sure to use tabs to indicate line indentation. Spaces are not currently supported.

Example: Bonsai tree for bid pricing

Step 3. Encode Your Decision Tree

Base64-encode your decision tree.

Example: Base64-encoded

Step 4. Check Your Decision Tree for Errors

Use the Custom Model Parser Service to check the validity of your decision tree. 

  • In the JSON request, put your base64-encoded tree in the model_text field as a string.
  • If there are errors, use the error field in the response to help you identify and resolve Bonsai syntax or feature errors. See Error Messages for guidance.
  • If there are no errors, the size field in the response shows you the size of your tree in Lisp (the format we use to store trees). Make sure the size is less than 3MB, or 3,145,728 bytes.

    If the tree is larger than 3MB, you will not be able to add the tree.

 Example: JSON file containing your base64-encoded tree

 Example: POST to the custom-model-parser service

Step 5. Add Your Decision Tree as a Custom Model

Once you've confirmed that your tree is valid, use the Custom Model Service to upload your encoded decision tree. Be sure to:

  • Set the correct custom model type in the model_output field:
    • For a Bid Price model, use "bid".
    • For a Bid Modifier model, use "bid_modifier".
  • Put your base64-encoded tree in the model_text field as a string.
  • Provide a unique name. This is required and will make it easier to select the correct model in the UI.
  • Provide the advertiser_id to which the custom model belongs. You will be able to use the model only in campaigns under this advertiser. 

Example: JSON file defining your custom model

Example: POST to custom-model service

Step 6. Assign Your Custom Model to a Campaign

This step changes depending on the type of custom model you are using and whether you're using the API or UI to assign your model to a campaign. Expand the relevant option below for instructions.

Bid Price Model

 Using the API

 Using the UI

Bid Modifier Model

 Using the API

 Using the UI

Related Topics