View a markdown version of this page

VAST request - AWS Elemental MediaTailor
When to useConfiguration fieldsHow the request is processedResponse fieldsHow parsed ads integrate with hook outputsFailure behaviorExample: Fetch ads from a secondary ad server

VAST request

When to use

Use VAST_REQUEST when your function needs to fetch ads from a Video Ad Serving Template (VAST) endpoint. MediaTailor sends the request, parses the response as VAST with wrapper redirects resolved, and makes the parsed ads available to your output expressions. Common use cases include fetching ads from a secondary ad server to supplement a short primary response, and retrieving house ads or promos to inject into underfilled ad breaks.

VAST_REQUEST functions are supported at the POST_ADS_RESPONSE and PRE_MANIFEST_INSERTION lifecycle hooks, on their own or as steps inside an executor. Ads parsed by a VAST_REQUEST function integrate with those hooks' outputs at full fidelity. For details, see How parsed ads integrate with hook outputs.

Configuration fields

A VAST_REQUEST function has the following fields:

  • Runtime — The expression language. Set this to JSONATA.

  • MethodType — The HTTP method. Supported values are GET (the default) and POST.

  • Url — The VAST endpoint to send the request to. You can use a static URL or a JSONata expression that builds the URL dynamically. A static URL must use the https scheme.

  • Headers — The HTTP headers to include in the request, specified as header name and value pairs. Use {%...%} expression syntax for dynamic header values.

  • Body — The request body to send. Used with POST requests, for example to send an OpenRTB bid request. You can use a JSONata expression to build the body dynamically.

  • RequestTimeoutMilliseconds (required) — How long to wait for a response.

  • Output — Defines the values to produce after the call completes. Each entry maps an output key to an expression that can reference the response object, including response.parsedAds.

The HTTP request limits that apply to HTTP_REQUEST functions also apply here. For details, see Limits.

How the request is processed

  1. Build the request — MediaTailor evaluates the Url, Headers, and Body expressions against the current session state, then sends the request. POST requests are sent with the application/json content type.

  2. Parse the response — MediaTailor parses the response body as VAST. If an ad is a VAST wrapper, MediaTailor follows the redirect chain and resolves it to the final inline ad. Wrapper redirect requests are always sent with GET, as the VAST specification requires. If your endpoint returns a document that contains a VAST URL instead of VAST itself (as some bidders do), chain an HTTP_REQUEST step that retrieves the URL, followed by a VAST_REQUEST step that fetches it.

  3. Process the parsed ads — MediaTailor evaluates the expressions in the output block. These expressions can reference the original session state and the response object.

Response fields

After the call completes, you can reference the following fields in your Output expressions:

Field Type Description
response.parsedAds Array The parsed ads, with wrapper redirects resolved. Each ad has the same shape as the adsResponse.ads entries at the POST_ADS_RESPONSE hook: adId, durationSeconds, adSystem, adTitle, creativeId, sequence, mediaFiles, and trackingEvents. Set to an empty array when the call fails or the response is not valid VAST.
response.statusCode Integer The HTTP status code returned by the endpoint. Set to null on network failure.

Because parsed ads use the same shape as adsResponse.ads, you can move expressions between the two surfaces without rewriting field references.

How parsed ads integrate with hook outputs

Every ad that a VAST_REQUEST function parses is retained internally by MediaTailor, keyed by the ad's VAST ad ID, for the duration of the hook invocation. This gives parsed ads first-class treatment in hook outputs:

  • At POST_ADS_RESPONSE, appending a parsed ad to adsResponse.ads by its adId restores the ad's complete parsed VAST data, including the full media file list and tracking events.

  • At PRE_MANIFEST_INSERTION, injecting an ad with just its vastAdId lets MediaTailor select the best media file and handle transcoding registration automatically.

Important

The retained ads don't carry over between hook invocations. A VAST_REQUEST call made at POST_ADS_RESPONSE is not available to a later PRE_MANIFEST_INSERTION invocation. Call VAST_REQUEST in the same hook's function chain where you use its results.

Failure behavior

If the call fails due to a network error or timeout, if the endpoint returns an HTTP error, or if the response can't be parsed as VAST, response.parsedAds is an empty array and the function chain continues. Check response.statusCode to distinguish an HTTP failure from a VAST response that genuinely contains no ads.

Tip

Keep RequestTimeoutMilliseconds tight. VAST wrapper resolution can involve multiple network round trips, and all of them count against the hook's timeout and the shared hook budget.

Example: Fetch ads from a secondary ad server

The following function fetches ads from a backup ad server and stores the parsed ads in temporary data. A CUSTOM_OUTPUT step later in the same sequence can append them to adsResponse.ads. It is designed for the POST_ADS_RESPONSE lifecycle hook.

{
    "FunctionId": "fetchBackupAds",
    "FunctionType": "VAST_REQUEST",
    "VastRequestConfiguration": {
        "Runtime": "JSONATA",
        "MethodType": "GET",
        "Url": "{%'https://backup-ads.example.com/vast?sid=' & session.uuid%}",
        "Headers": {
            "Accept": "application/xml"
        },
        "RequestTimeoutMilliseconds": 1000,
        "Output": {
            "temp.backupAds": "{%response.parsedAds%}"
        }
    }
}

To send an OpenRTB bid request instead, set MethodType to POST and provide the bid request in Body. The bidder must return VAST in the response body.

For a complete walkthrough of a similar example, see Function examples.