For the complete documentation index, see llms.txt. This page is also available as Markdown.

VAST Endpoint URL Parameters

The VAST endpoint provides a video ad tag URL that you can paste into an ad platform or VAST-compatible video player. When the URL is requested, it returns instructions telling the player which video to play, where clicks should go, and how to track playback.

The endpoint can select different published videos based on the device and geographic market.

Note: This page is a reference for the tag URL itself. To create and publish the creative behind it, see VAST Video & CTV Ads.

Getting started

  1. Obtain the published VAST tag URL for your creative or deployment.

  2. Paste the complete URL into your platform's VAST tag or video ad tag field.

  3. Preview the ad in that platform or a compatible VAST player.

Note: Opening the URL directly in a browser normally displays XML text. To watch the ad, use a VAST player.

A basic URL looks like this:

https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_ID

Replace CREATIVE_ID with your creative's actual ID. The examples below use placeholders and will not serve an ad until those placeholders are replaced.

If you already have a published tag URL, start with that URL and preserve its existing settings.

How URL options work

URL parameters are settings added after the creative ID.

  • Start the first parameter with ?.

  • Separate additional parameters with &.

  • Use the lowercase parameter names and values shown in this guide.

If your URL already contains ?, add further parameters with &. For example, this requests a specific deployment using VAST 3.0:

Available URL parameters

Parameter
What it controls
Example

did

Selects a particular published deployment of the creative

did=DEPLOYMENT_ID

vast

Selects the VAST format required by the player

vast=3

device

Overrides the device detected by the endpoint

device=roku

dma

Overrides the geographic market used for targeting

dma=501

Deployment: did

A deployment is a particular published configuration of a creative. Different deployments can have different videos or targeting rules.

Use the deployment ID supplied with your published tag:

If did is omitted or empty, the endpoint uses the creative's main published configuration.

VAST format: vast

Use this option when your ad platform or player requires a particular VAST version.

URL setting
Format returned

vast=2

VAST 2.0

vast=3

VAST 3.0

vast=4

VAST 4.2

Use vast=4, not vast=4.2.

If this parameter is omitted, the endpoint chooses a format based on the detected or specified device:

  • iPhone, iPad, and Apple TV: VAST 2.0

  • Other device categories: VAST 4.2

An explicit vast setting takes priority over these defaults.

Note: VAST 2.0 and 3.0 return video without the SIMID interactive layer. VAST 4.2 can include that layer when interactivity has been enabled for the published creative. The player must also support SIMID to display it.

Device: device

The endpoint normally identifies the device from information sent with the request. Use device to supply a known device category or to check device-specific targeting:

Supported values:

Value
Device category

roku

Roku

firetv

Amazon Fire TV

tvos

Apple TV

tizen

Samsung smart TVs

webos

LG smart TVs

androidtv

Android TV

ios

iPhone and iPad

android

Android phones and tablets

ctv

General connected TV category

mobile

General mobile category

desktop

Desktop and laptop computers

Specific devices can also match broader published targeting rules. For example, Roku can match a general connected TV rule, and iPhone can match a general mobile rule.

Geographic market: dma

DMA stands for Designated Market Area: a geographic television market. Use a numeric DMA code to request an ad for a particular market, for example:

  • dma=501: New York

  • dma=803: Los Angeles

Enter the DMA code, not a city name, ZIP code, or state abbreviation.

Without this parameter, the endpoint attempts to identify the market from the requesting IP address when the published creative has DMA targeting rules. If the market cannot be identified, it can still serve another matching video or a configured default video.

A fixed dma value applies that market to every request using the URL. Use it for a deliberate market override or testing.

Note: If an ad server requests the tag on a viewer's behalf, automatic location detection may reflect the server's location.

Combining options

You can combine parameters in any order.

Request a deployment using VAST 3.0:

Check Roku targeting for New York using VAST 3.0:

Check Apple TV targeting with its automatic VAST format:

The last example returns VAST 2.0 because no explicit vast setting is supplied.

How the video is selected

These settings work with the videos and targeting rules already published for the selected creative or deployment. Adding a parameter does not create a new video variation.

The endpoint uses the first published rule that matches the request. If nothing matches, it uses the configured default video, when one exists. Otherwise, it returns no ad.

If the ad does not appear

Check that:

  • The creative and selected deployment have been published.

  • The creative ID and any did value are correct.

  • The URL uses one ?, followed by & between additional parameters.

  • The requested device and market have a matching video or a configured default.

  • The selected VAST format is supported by your player.

Unsupported device or vast values are ignored and automatic selection is used instead. A dma value containing anything other than digits is also ignored.

Note: A URL can load successfully while returning an empty VAST response, meaning no ad is available for that request.

Last updated

Was this helpful?