---
title: "Check what a URL returns"
type: reference
method: GET
path: /rest-api/url-check.do
tag: "Banners"
---

# Check what a URL returns

`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

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `url` | string | yes | `https://cdn.example.com/video/spot-30s.mp4` | The URL to request, http or https |
| `as` | string | no | `iphone` | The device the request poses as: desktop (default), iphone or android |
| `mode` | string | no | `vast` | auto (default: VAST or page by the body), head (status and headers only), vast or page |

## 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

## Example request

```bash
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'
```

Source: https://epom.com/ad-server/docs/api/banners/get-url-check