> For the complete documentation index, see [llms.txt](https://docs.responsiveads.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.responsiveads.com/deploying-ads/vast-video-and-ctv-ads/vast-endpoint-url-parameters.md).

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

{% hint style="info" %}
**Note:** This page is a reference for the tag URL itself. To create and publish the creative behind it, see [VAST Video & CTV Ads](https://docs.responsiveads.com/deploying-ads/vast-video-and-ctv-ads.md).
{% endhint %}

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

{% hint style="info" %}
**Note:** Opening the URL directly in a browser normally displays XML text. To watch the ad, use a VAST player.
{% endhint %}

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:

```
https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_ID?did=DEPLOYMENT_ID&vast=3
```

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

```
?did=DEPLOYMENT_ID
```

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

{% hint style="warning" %}
**Warning:** Keep `did` in place when it is included in your supplied URL. If the specified deployment is unavailable, the endpoint returns no ad; it does not automatically switch to the creative's main configuration.
{% endhint %}

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

{% hint style="info" %}
**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.
{% endhint %}

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

```
?device=roku
```

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.

{% hint style="warning" %}
**Warning:** Changing this parameter changes how the endpoint selects the ad. It does not emulate that device's player or guarantee playback compatibility. The device setting also affects the automatic VAST version unless you specify `vast` separately.
{% endhint %}

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

```
?dma=501
```

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.

{% hint style="info" %}
**Note:** If an ad server requests the tag on a viewer's behalf, automatic location detection may reflect the server's location.
{% endhint %}

## Combining options

You can combine parameters in any order.

Request a deployment using VAST 3.0:

```
https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_ID?did=DEPLOYMENT_ID&vast=3
```

Check Roku targeting for New York using VAST 3.0:

```
https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_ID?did=DEPLOYMENT_ID&device=roku&dma=501&vast=3
```

Check Apple TV targeting with its automatic VAST format:

```
https://lj1156ugt5.execute-api.us-east-1.amazonaws.com/vast/CREATIVE_ID?did=DEPLOYMENT_ID&device=tvos
```

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.

{% hint style="info" %}
**Note:** A URL can load successfully while returning an empty VAST response, meaning no ad is available for that request.
{% endhint %}
