Check what a URL returns

Reference

GET https://YOUR-NETWORK-DOMAIN/rest-api/url-check.do

Requests the URL from the ad server's own network, as a browser on the chosen device would, and reports what came back: the final status, every redirect (status, from and to - hosts in full, paths shortened, queries left out), the content type, the declared length and the bytes read, and the time taken. Good for a media file, click URL or pixel that answers 404 or redirects oddly, for what a VAST tag actually returns, and for finding the video player on a publisher page. mode=vast (or auto on a VAST body) summarises the VAST: version, each ad as InLine or Wrapper, its ad system, creatives, media files (type, size, bitrate, delivery, VPAID), impression/error/tracking counts and the click-through host; a Wrapper is followed up to 3 levels; a VAST without an ad answers noAd. mode=page (or auto on HTML) lists the page title and the elements of its raw HTML that look like a player - video elements, player iframes, ids and classes naming a player - each with a CSS selector; no JavaScript is run. mode=head reads only the status and headers. Only http and https URLs on the public internet are requested, every redirect hop included; at most 5 redirects, 5 seconds to connect and to read, and 2 MB of body. The request comes from a datacenter, so an answer targeted by country, device or IP may differ from a real visitor's. Requires VIEW permission on campaigns or on inventory (shared or all); 30 checks per minute per user.

Query Params

url string required

The URL to request, http or https

https://cdn.example.com/video/spot-30s.mp4

as string

The device the request poses as: desktop (default), iphone or android

iphone

mode string

auto (default: VAST or page by the body), head (status and headers only), vast or page

vast

Responses

200

{success, url, device, userAgent, status, finalHost, redirects:[{status, from, location, ms}], contentType, contentLength, bytesRead, truncated, ms, error:{code, message}, readAs, vast:{version, ads, noAd, ad:[..]}, noAdExplanation, wrapperChain:[{depth, host, status, vast}], page:{title, candidates:[{selector, tag, why, matches}], playerScripts, note}}; error.code is one of FORBIDDEN_REDIRECT, TOO_MANY_REDIRECTS, BAD_REDIRECT, TIMEOUT, UNKNOWN_HOST, UNREACHABLE

400

The URL is not http(s), has no host or carries a user name, its host is not on the public internet, or device or mode is unknown

401

Authentication error

403

No VIEW permission on campaigns or on inventory

429

More than 30 checks in the last minute

Language

cURL Request

curl --request GET \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast' \
  --header 'X-Api-Key: YOUR_API_KEY'

Python Request

import requests

response = requests.request("GET", "https://YOUR-NETWORK-DOMAIN/rest-api/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast", headers={"X-Api-Key": "YOUR_API_KEY"})
print(response.json())

Node Request

const response = await fetch('https://YOUR-NETWORK-DOMAIN/rest-api/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast', {
  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/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast"))
    .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/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast");
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/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast", 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/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast");
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/url-check.do?url=https%3A%2F%2Fcdn.example.com%2Fvideo%2Fspot-30s.mp4&as=iphone&mode=vast")
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