Bidder Instance Service
A bidder will likely have at least two instances running at any given time. Each instance is associated with the impression bus in one of the Xandr datacenters. The instance itself may either be hosted with Xandr at the datacenter or located nearby. To decrease latency for global impressions, you may set up bidder instances in the various Xandr datacenters (see
datacenter_id below). Each bidder instance is associated with one datacenter. As load on your bidders increases, you will likely require multiple instances per datacenter. Instead of setting up your own local load-balancing pool for these multiple instances, the impression bus can handle the load balancing for you.
You will need to register the hostname/IP/port combination for each of your bidder instances with the impression bus using the Bidder Instance Service API. This API service also allows you to view, modify, and remove any instances. Each bidder instance must use the nomenclature for request handlers that is defined by the Bidder Service.
For answers to frequently asked questions about how bidder instances work, see the Bidder Instance - FAQ.
To see all bidder instances (will not show other users' bidders):
To see a particular bidder instance:
To add a new bidder instance:
(bidder instance JSON)
To modify an existing bidder (note limitations above):
(bidder instance JSON)
The bidder instance service currently does not support deletes - to remove an instance, please set it to inactive.
When creating/modifying bidder instances, never use the deprecated "datacenter" parameter to set the datacenter for your instance. Instead, always use the "datacenter_id" parameter with the IDs defined below.
yes (on PUT)
The ID of the bidder instance.
The ID of the bidder.
no, default is true
Whether the bidder instance is active or not.
The datacenter ID with which your instance is associated (NYM = 6, LAX = 4, AMS = 12, SIN = 8, FRA = 7).
IP address for the bidder instance.
Port for the bidder instance.
The timestamp of last modification to this bidder instance.
The hostname for the bidder instance (Be sure not to include 'http://' - eg. "hostname":"rtb.yourdomain.com")
|qps_limit||no||int||The max queries per second sent to this bidder instance.|
QPS limits can also be set at a datacenter level instead of a bidder instance level. To do this, set the qps_limit to the same value for all bidder instances active in a datacenter. For example, if you have three bidder instances in LAX, and want to set the QPS limit to 50,000 for the entire datacenter, you would set the qps_limit to 50000 on each of the three bidder instances.
You can add a hostname to your bidder instance at any time. However, our api requires an ip address when adjusting the bidder instance, but if you include a hostname field with a value (your url or domain) in the api call, our systems will connect to the hostname and ignore the ip address.
Authentication is always the first step when using the API Services. The authentication token can then be written to our cookie file for future use. Please see Authentication Service for more detailed instructions.
View Existing Instances
Add New Instance
I have a New York (NYM2) instance; now I want to register my LAX1 bidder instance. I create the following JSON:
Then to add this new instance to my bidder (2):
And to view the newly added instance:
Add a QPS cap to an existing instance
If I want to add a QPS cap to an existing instance:
Then if I want to view the instance:
Modifying an Instance
If I need to change an IP address:
Then to view the current status of all instances for my bidder(2):