/

Browse the help center

Get banner delivery probability

Simulates an ad request to the placement and returns each eligible banner with the probability it is served, as the console's Banners Probability card does.

Reference

GET https://YOUR-NETWORK-DOMAIN/rest-api/placements/{placementId}/banner-probability.do

Simulates an ad request to the placement and returns each eligible banner with the probability it is served, as the console's Banners Probability card does. Country, browser, operating system and mobile carrier describe the simulated visitor; a dimension that is not sent is simulated as unknown, which still fails a rule that targets it. List a dimension in ignore to leave its targeting out of the match altogether. A banner that matches the simulated visitor but gets no share of the rotation - zero weight, or House ads priority beside other campaigns - is returned with probability -1. A linked banner that does not match the visitor, is paused, or belongs to a paused or ended campaign is not in the simulation and is not listed; read the placement's banners for those. Group by CAMPAIGN or ADVERTISER to sum the rows. Requires ENABLED level on the BANNERS_PROBABILITY_VISIBILITY permission and VIEW access to the placement's site.

Path Params

placementId integer required

Placement ID

4001

Query Params

browser string

Browser of the simulated visitor

CHROME

countryCode string

ISO 3166 country code of the simulated visitor

US

dir string

ASC or DESC

DESC

group string

BANNER, CAMPAIGN or ADVERTISER; the latter two sum the probabilities per campaign or advertiser

BANNER

ignore array<string>

Targeting to leave out of the match

BROWSER,OPERATING_SYSTEM

limit integer

Rows per page, 1 to 1000

50

mobileCarrier string

Mobile carrier of the simulated visitor

Verizon

operatingSystem string

Operating system of the simulated visitor

ANDROID

priority string

Count only campaigns of this delivery priority; IGNORE counts all

STANDARD_HIGH

query string

Keep only rows whose banner, campaign or advertiser name contains this text

summer

sort string

bannerName, campaignName, advertiserName or probability

probability

start integer

Offset of the first row returned

0

Responses

200

{success, total, data:[{bannerId, bannerName, campaignId, campaignName, advertiserId, advertiserName, probability}]}

400

An invalid enum, group, sort, dir, start or limit; the error names the field and the accepted values

401

Authentication error

403

No BANNERS_PROBABILITY_VISIBILITY permission, or no VIEW access to the site

404

Placement not found or deleted

Language

cURL Request

curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC' \
  --header 'X-Api-Key: YOUR_API_KEY'

Python Request

import requests

response = requests.request("GET", "https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC", headers={"X-Api-Key": "YOUR_API_KEY"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC', {
  method: 'GET',
  headers: { 'X-Api-Key': 'YOUR_API_KEY' },
});

console.log(await response.json());

Java Request

HttpClient client = HttpClient.newHttpClient();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC"))
    .header("X-Api-Key", "YOUR_API_KEY")
    .method("GET", HttpRequest.BodyPublishers.noBody())
    .build();

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

C# Request

using var client = new HttpClient();

var request = new HttpRequestMessage(new HttpMethod("GET"), "https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

Go Request

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC", nil)
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
}

PHP Request

<?php
$ch = curl_init("https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "GET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Api-Key: YOUR_API_KEY"]);

echo curl_exec($ch);
curl_close($ch);

Ruby Request

require 'net/http'
require 'json'

uri = URI("https://YOUR-NETWORK-DOMAIN/rest-api/placements/4001/banner-probability.do?browser=CHROME&countryCode=US&dir=DESC")
request = Net::HTTP::Get.new(uri)
request['X-Api-Key'] = 'YOUR_API_KEY'

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }
puts response.body