Basic request

The smallest useful call to /v1alpha2/ads is just the player identity. This is the baseline every player must support.

GET /v1alpha2/ads?playerid=screen-01&key=retailer-acme

Param	Required	Description
playerid	yes	The player’s device id, scoped by key.
key	yes	Retailer scope for playerid.

The server selects using whatever it already knows about the device: its configuration (location, zone, ad networks, supported formats) and any audience context previously pushed for it out-of-band via /adsignals (see When signals apply). It returns a fully targeted decision when context exists, or an empty <VAST/> when nothing is eligible (or the device’s context is still warming). See Response.

Additional request parameters

On top of the required playerid + key identity, the request takes these optional parameters:

GET /v1alpha2/ads?playerid=<player_id>&key=<retailer_key>[&limit=<N>][&source=<SRC>...] HTTP/1.1

Param	Required	Description
limit	no	How many ads. Online default 1; a higher value returns a pod to play in order. Offline defaults to the server-side cap; a smaller limit requests fewer. Clamped server-side.
source	no	Restrict the response to one or more source types: SOURCE_TYPE_AD_SERVER, SOURCE_TYPE_SSP, SOURCE_TYPE_CMS. Repeatable (&source=SOURCE_TYPE_SSP&source=SOURCE_TYPE_CMS); multiple values are OR’d. Applied after the server’s normal selection, so only matching winners are returned. Default: all sources. In offline mode the server draws from every source eligible for offline delivery instead of routing per opportunity, so the player-side rotation (grouped by source_id) is what honors the player’s source mix.
retail_grocery_zone	no	The grocery zone the player currently is in, e.g. VENUE_RETAIL_GROCERY_CHECK_OUT. Single-valued; mutually exclusive with retail_mall_zone; requires SENSOR_LOCATION; online only. See Position.
retail_mall_zone	no	The mall zone the player currently is in, e.g. VENUE_RETAIL_MALLS_FOOD_COURT. Single-valued; mutually exclusive with retail_grocery_zone; requires SENSOR_LOCATION; online only. See Position.
aisle	no	The grocery product aisle the player currently is at, e.g. AISLE_DAIRY. Single-valued; requires SENSOR_LOCATION; online only. Implies the grocery Aisles zone. See Position.

Modes

The offline parameter selects one of two modes:

Online (default)

offline=false (or omitted). Ask for an ad to play right now, in the next slot.

• Returns 1 ad by default; a higher limit returns a pod: several ads to play in order in one break.
• These ads are for imminent playback, not to be stored and played later. To hold ads for later, pre-fetch with offline=true.

GET /v1alpha2/ads?playerid=screen-01&key=retailer-acme

Ask slightly ahead of the slot

Request the ad a little before the slot it plays in, rather than at the moment the slot opens, so the player has time to download a creative it has not already cached. Keep the lead short: the ad is selected for the audience present when the request arrives. Pick the value that suits the player’s own timings, or ask us and we will help size it.

Offline

offline=true. Ask for the full eligible playlist to store on the player and rotate through over time.

• Returns up to a server-side cap; a smaller limit requests fewer.
• These ads are built to be stored and played later. For how to store and rotate them, see Operating offline.

GET /v1alpha2/ads?playerid=screen-01&key=retailer-acme&offline=true

How to read a multi-ad response

The mode decides what several ads mean.

• Online, they are a pod. Each <Ad> carries a sequence attribute. Play them in that order, one per slot, starting with the next slot, and do not store them for later.
• Offline, they are a set to choose from. No sequence; order does not matter. Store the set and rotate through it over time. Two ads may belong to one flight, each with a different creative and its own tracking, but a frequency cap counts across them; see Several ads may share one flight and Enforcing frequency caps offline.

Two terms to keep separate:

Term	What it means
Playlist	The set of ads the player stores.
Creative	Each ad’s <MediaFile> bytes that the player downloads.

Response

Every request returns 200 OK with a VAST 4.2 XML document (Content-Type: application/xml). The body holds zero or more <Ad> elements.

Each ad references a creative in one of three formats:

Format	<MediaFile type>
Video	video/mp4
Image	image/png, image/jpeg
HTML5	application/zip

Dispatch on the <MediaFile type> attribute to decide how to render each ad. For the full list and rendering rules, see Creative formats.

Empty responses (no-fill)

An empty document — <VAST version="4.2"></VAST> with zero <Ad> elements — means no-fill. It is a normal outcome, not an error, and the player should always respond the same way: play from its stored playlist.

A correctly registered screen receives an empty response whenever:

• no ad is currently eligible for it, or
• its audience context is still warming, or
• the playerid is unknown or not yet registered.

There is no separate “unknown player” status and no 404 — every one of these cases is an empty 200. Treat any empty response as “play from the stored playlist.”

Warm a fresh player

A brand-new player has an empty creative cache. The first response it gets references a creative it has never seen, so at slot time it must download that media file — potentially a large video — before it can play. That live download can overrun the slot and cause a timeout.

Run an offline=true pre-fetch and download the returned media files up front. Start playing as soon as the first one is downloaded. With the creatives already cached, later requests play from local storage instead of downloading at slot time.

See the Ads API reference for a full response example and schema.

Status codes

HTTP	Meaning	The player’s action
200	Success (may be empty <VAST/>)	Play, or fall back to playlist
400	Validation failure, e.g. missing playerid/key; dvactid/seg/products/a position with offline=true; a malformed seg/products value, an unsupported or unknown seg segment, seg on a device with no demographic sensor, or a zone/aisle combination that is not a valid position	Fix the request
429	Rate-limited by the edge	Back off and retry; the response carries no Retry-After, so use your own interval with jitter
500	Infrastructure failure	Retry with backoff

A 2xx response carries the VAST document (or an empty body). A failure returns a JSON error, in one of two shapes depending on whether the service or the gateway raised it — see Troubleshooting for how to tell them apart and how to read a validation failure.

An unknown, unregistered, or not-yet-warmed playerid does not return an error: the request succeeds with an empty <VAST/> (no-fill). There is no 404 for “unknown player.”

Requirements

MUST

• Fire every <Impression> and <Tracking> pixel. With a VAST SDK, disable its built-in firing and drive fires from its progress callbacks.
• Fire each stamped event at its lifecycle moment and let the platform decide what counts.
• Append ets (occurrence time) to every fire, and preserve it unchanged when the player replays a buffered fire.
• Fire the server-stamped URLs verbatim: never strip or rewrite the token.
• Treat <VAST/> as no-fill; 4xx as permanent; 5xx as transient (retry with backoff, then fall back to playlist).
• Drop expired ads from the playlist at slot time, unless none is left and the player cannot refresh; see When the player cannot refresh.
• Offline, honor the player’s source mix by grouping stored ads by source_id.
• Pre-fetch with offline=true on every boot and on a schedule, and do not wait for it to finish before playing; see Caching creatives.
• When an online ad’s creative is not cached in time, play a stored ad instead; see When the file is not there.
• Bound GET /v1alpha2/ads with a client-side timeout at slot time; fall back to the playlist.

MUST NOT

• Mint or modify the tracking token.
• Block other ads on one ad’s failure.
• Fire an <Impression> or <Tracking> URL of an ad that did not play.