VAST macros: the full list

VAST macros are substitution tokens of the form [MACRO] that ad servers and players replace with real values inside tracking, click, error, impression, and media URLs at request time. They carry everything from cache busters and timestamps to device identifiers, consent strings, playhead positions, and error codes.

The macro list was formalised in the IAB VAST 4.x spec and is maintained separately on GitHub. vastlint validates 51 of these macros: it flags unknown tokens (usually typos), macros written in the wrong case, deprecated playhead macros, macros used where they have no defined value, and macro-bearing URLs with characters that must be percent-encoded.

How macros work

Macro substitution is case-sensitive and only happens inside URL fields. Two rules cover most real-world breakage:

Always uppercase. A player replaces [CACHEBUSTING] but not [cachebusting], which is sent to the server as literal text.
Context matters. [ERRORCODE] only resolves inside an <Error> URI, and [REASON] only inside a verificationNotExecuted tracking URI. Elsewhere they resolve to nothing.

Example: a macro-rich impression URL

<Impression><![CDATA[https://t.example.com/i?cb=[CACHEBUSTING]&ts=[TIMESTAMP]&ifa=[IFA]&gdpr=[GDPR]&consent=[GDPRCONSENT]&ph=[ADPLAYHEAD]]]></Impression>

<Impression><![CDATA[https://t.example.com/i?cb=[CACHEBUSTING]&ts=[TIMESTAMP]&ifa=[IFA]&gdpr=[GDPR]&consent=[GDPRCONSENT]&ph=[ADPLAYHEAD]]]></Impression>

VAST XML fragment only. This excerpt belongs inside a complete VAST document, so standalone validation will fail until it is wrapped in a full <VAST>response.

Values that are themselves URLs or contain reserved characters (such as [PAGEURL], [ASSETURI], or [TIMESTAMP]) must be percent-encoded so the substituted URL stays valid.

Validate macros before launch

# Flags unknown, mis-cased, deprecated, out-of-context, and unencoded macros
vastlint check creative.xml

# Flags unknown, mis-cased, deprecated, out-of-context, and unencoded macros
vastlint check creative.xml

The macro rules that back these checks:

Use the right tool for this failure

If you already have the resolved XML, run a pure spec check. If you only have a live tag URL, test that endpoint first. If the failure happens in the wrapper chain, inspect each hop.

Validate this XML →Test this live URL →Inspect this wrapper chain →

Every VAST macro

Each macro has a dedicated page with its meaning, an example of the substituted value, where it is valid, and the vastlint rules that catch it before launch.

Identity and privacy

Macro	Resolves to
`[IFA]`	The device advertising identifier (IDFA, AAID, or CTV ad ID) for the request.
`[IFATYPE]`	The type of advertising identifier carried in [IFA] (e.g. idfa, aaid, rida).
`[LIMITADTRACKING]`	Whether the user has enabled limit ad tracking (1) or not (0).
`[GDPR]`	Binary flag for whether GDPR applies to this request (1) or not (0).
`[GDPRCONSENT]`	The IAB TCF consent string (base64url) for the request.
`[REGULATIONS]`	Active privacy regulations for the request (e.g. GDPR, COPPA, CCPA).
`[DOMAIN]`	The domain of the site or app where the ad is served.
`[PAGEURL]`	The full URL of the page where the ad is displayed.
`[APPBUNDLE]`	The app bundle or package identifier in app environments.

Player and device

Macro	Resolves to
`[CLIENTUA]`	The user agent of the client player making the request.
`[SERVERUA]`	The user agent of the server making a server-side request.
`[DEVICEUA]`	The user agent of the end-user device.
`[DEVICEIP]`	The IP address of the end-user device.
`[LATLONG]`	The device latitude and longitude, when available and permitted.
`[PLAYERCAPABILITIES]`	The capabilities the player supports (e.g. skip, mute, OMID, SIMID).
`[PLAYERSIZE]`	The width and height of the player in pixels.
`[PLAYERSTATE]`	The player state at request time (e.g. muted, fullscreen).
`[SERVERSIDE]`	Whether the request was made client-side (0), server-side (1), or hybrid (2).
`[INVENTORYSTATE]`	Inventory characteristics such as autoplay, muted, or skippable.
`[PLACEMENTTYPE]`	The placement type for the ad (in-stream, in-banner, in-article, etc.).

Playback and timing

Macro	Resolves to
`[ADPLAYHEAD]`	The current playhead position within the ad creative.
`[CONTENTPLAYHEAD]` (deprecated)	Deprecated playhead macro; use [ADPLAYHEAD] instead.
`[MEDIAPLAYHEAD]` (deprecated)	Deprecated playhead macro; use [ADPLAYHEAD] instead.
`[ASSETURI]`	The URI of the media asset currently being played.
`[CONTENTID]`	An identifier for the content the ad plays alongside.
`[CONTENTURI]`	The URI of the content the ad plays alongside.
`[MEDIAMIME]`	The MIME types the player can render.
`[CLICKPOS]`	The x,y coordinates of a click within the player.

Ad and pod

Macro	Resolves to
`[ADCOUNT]`	The position of this ad within an ad pod.
`[ADTYPE]`	The type of ad: video, audio, or hybrid.
`[PODSEQUENCE]`	The sequence number of the ad within its pod.
`[ADSERVINGID]`	The unique ad-serving identifier shared across the supply chain.
`[UNIVERSALADID]`	The creative's UniversalAdId (registry and value).
`[ADCATEGORIES]`	The content categories declared for the ad.
`[BLOCKEDADCATEGORIES]`	Categories the publisher has blocked for this request.
`[BREAKPOSITION]`	The position of the ad break: pre-roll, mid-roll, or post-roll.
`[BREAKMAXADS]`	The maximum number of ads allowed in the break.
`[BREAKMINADLENGTH]`	The minimum allowed duration of a single ad in the break (seconds).
`[BREAKMAXADLENGTH]`	The maximum allowed duration of a single ad in the break (seconds).
`[BREAKMINDURATION]`	The minimum total duration of the ad break (seconds).
`[BREAKMAXDURATION]`	The maximum total duration of the ad break (seconds).
`[TRANSACTIONID]`	A unique identifier for this ad request transaction.
`[VASTVERSIONS]`	The VAST versions the player supports.
`[APIFRAMEWORKS]`	The API frameworks the player supports (e.g. OMID, SIMID, VPAID).
`[EXTENSIONS]`	Custom extension data passed through in the request.

Verification

Macro	Resolves to
`[VERIFICATIONVENDORS]`	The verification vendors present in the ad response.
`[OMIDPARTNER]`	The Open Measurement partner name and version.
`[REASON]`	Why a verification script was not executed (code 1, 2, or 3).

Cachebusting and error

Macro	Resolves to
`[CACHEBUSTING]`	A random value that prevents caching of a tracking request.
`[TIMESTAMP]`	The ISO 8601 timestamp when the macro is replaced.
`[ERRORCODE]`	The VAST error code for a failure, substituted in Error URIs.