Skip to end of metadata
Go to start of metadata

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.

On This Page

REST API

To see all bidder instances (will not show other users' bidders):
GET https://api.adnxs.com/bidder-instance/BIDDER_ID

To see a particular bidder instance:
GET https://api.adnxs.com/bidder-instance/BIDDER_ID/BIDDER_INSTANCE_ID

To add a new bidder instance:
POST https://api.adnxs.com/bidder-instance/BIDDER_ID
(bidder instance JSON)

To modify an existing bidder (note limitations above):
PUT https://api.adnxs.com/bidder-instance/BIDDER_ID/BIDDER_INSTANCE_ID
(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.

JSON structure

Field

Required

Type

Description

id

yes (on PUT)

int

The ID of the bidder instance.

bidder_id

yes

int

The ID of the bidder.

active

no, default is true

boolean

Whether the bidder instance is active or not.

datacenter_id

yes

int

The datacenter ID with which your instance is associated (NYM = 6, LAX = 4, AMS = 12, SIN = 8, FRA = 7).

ip_address

yes

string

IP address for the bidder instance.

port

yes

int

Port for the bidder instance.

last_activity

no

timestamp

The timestamp of last modification to this bidder instance.

hostname

no

varchar(128)

The hostname for the bidder instance (Be sure not to include 'http://' - eg. "hostname":"rtb.yourdomain.com")

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

Examples

Authentication Token
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):

Related Topics

  • No labels