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.
Getting started
Obtain the published VAST tag URL for your creative or deployment.
Paste the complete URL into your platform's VAST tag or video ad tag field.
Preview the ad in that platform or a compatible VAST player.
A basic URL looks like this:
https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_IDReplace 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
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.
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.
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:
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 Yorkdma=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.
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
didvalue 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.
Last updated
Was this helpful?