MediaTailor service variables for session control
AWS Elemental MediaTailor reserves the aws. query parameter namespace for service
variables that control session-level behavior. Unlike ads. parameters
(which are forwarded to the ADS) and manifest. parameters (which are
appended to the personalized manifest URLs), aws. parameters are consumed
directly by MediaTailor and are not forwarded to the origin server or the ADS.
Supported parameters
The following table lists the aws.* parameters you can use to
control session-level behavior.
| Parameter | Type | Values | Default | Description |
|---|---|---|---|---|
aws.startTime |
ISO 8601 timestamp | For example, 2026-06-17T10:00:00Z |
Not set (live-edge join) | Starts the session at a specific point in the DVR window.
MediaTailor resolves the timestamp to the nearest segment boundary and
emits EXT-X-START:TIME-OFFSET in the HLS
manifest. |
aws.preroll |
String enum | enabled, disabled
(case-insensitive) |
enabled |
Controls whether pre-roll ad insertion occurs for the session.
When disabled, pre-roll is suppressed even if the
playback configuration has a
LivePreRollConfiguration. |
aws.overlayAvails |
String enum | on, off (case-insensitive) |
on |
Controls whether overlay (non-linear) ad avails are processed
for the session. When off, overlay ad markers in
the source manifest are ignored and no overlay ads are
inserted. |
aws.logMode |
String enum | DEBUG, DISABLED |
DISABLED |
Enables verbose debug logging for the session. When set to
DEBUG, MediaTailor emits detailed session logs to
CloudWatch Logs for troubleshooting. |
aws.availSuppressionMode |
String enum | OFF, BEHIND_LIVE_EDGE,
AFTER_LIVE_EDGE (case-insensitive) |
OFF |
Controls whether ad avails are suppressed based on their position relative to the live edge. |
aws.availSuppressionValue |
Time duration | HH:MM:SS format (for example,
00:00:10) |
Not set | The time window for avail suppression. Required when
availSuppressionMode is
BEHIND_LIVE_EDGE or
AFTER_LIVE_EDGE. |
aws.availSuppressionFillPolicy |
String enum | FULL_AVAIL_ONLY, PARTIAL_AVAIL
(case-insensitive) |
FULL_AVAIL_ONLY |
When mode is AFTER_LIVE_EDGE, controls whether
partially-suppressed avails are filled. |
aws.contentReserveSeconds |
Integer (seconds) | At least 1 |
Not set (dynamic avail sizing off) | Sets the size of the content reserve and turns on dynamic avail sizing for the session. For more information, see aws.contentReserveSeconds. |
aws.maxAvailInflationSeconds |
Integer (seconds) | 0 to 120 (0 turns
inflation off) |
120 |
Sets the maximum time that MediaTailor adds to a single avail when it inflates to refill the content reserve. For more information, see aws.maxAvailInflationSeconds. |
aws.replenishmentThresholdSeconds |
Integer (seconds) | 0 up to the value of
aws.contentReserveSeconds |
0 |
Sets the minimum deficit that triggers inflation. For more information, see aws.replenishmentThresholdSeconds. |
aws.startTime
When aws.startTime is set, MediaTailor starts the session at the
segment boundary nearest the specified program date-time.
Usage
Pass aws.startTime as a query parameter in the manifest
request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.startTime=2026-06-17T10:00:00Z
Or in explicit session initialization, pass it as a top-level field without
the aws. prefix:
POST /v1/session/{hashed-account-id}/{origin-id}/{asset}.m3u8 { "startTime": "2026-06-17T10:00:00Z" }
Requirements
The following requirements apply to aws.startTime:
-
The source manifest must contain
EXT-X-PROGRAM-DATE-TIME(PDT) on segments. Without PDT,aws.startTimecannot resolve and is ignored. -
Applies to HLS live sessions only (both SSAI and SGAI).
Behavior
The following table describes how aws.startTime behaves in
different scenarios:
| Scenario | Result |
|---|---|
| Timestamp within DVR window | Start at nearest segment boundary, emit
EXT-X-START |
| Timestamp older than DVR window | Clamp to 3×targetDuration from window head |
| Timestamp within 3×targetDuration of live edge | Treat as live-edge join (no
EXT-X-START) |
| Timestamp at or after live edge | Normal live-edge join |
| Malformed or not ISO 8601 | Ignored – fall back to live-edge join, error logged |
| Manifest has no PDT | Ignored – fall back to live-edge join, error logged |
| Parameter omitted | Default: normal live-edge join |
Clamping behavior
If the start point ages out of the DVR window mid-session,
EXT-X-START is clamped to 3×targetDuration from the
window head. The 3×targetDuration buffer aligns with RFC 8216
§6.3.3 player buffering recommendations.
Example Manifest output with aws.startTime
When a player initializes a session with
aws.startTime=2026-06-17T10:00:00Z and the resolved offset
is 120 seconds from the live edge, MediaTailor emits:
#EXTM3U #EXT-X-TARGETDURATION:6 #EXT-X-START:TIME-OFFSET=-120.120,PRECISE=YES #EXT-X-MEDIA-SEQUENCE:500 #EXT-X-PROGRAM-DATE-TIME:2026-06-17T09:58:00.000Z #EXTINF:6.006, segment500.ts #EXTINF:6.006, segment501.ts ...
The TIME-OFFSET=-120.120 tells the player to begin playback
120 seconds behind the live edge, at the segment boundary nearest the
requested start time.
Limitations
The following limitations apply:
-
You cannot change this parameter after session initialization.
-
Requires
EXT-X-PROGRAM-DATE-TIMEin the source manifest. -
EXT-X-STARTis a player hint – MediaTailor cannot guarantee all players honor it.
aws.preroll
When aws.preroll=disabled, MediaTailor suppresses pre-roll ad
insertion for the session even if the playback configuration has a
LivePreRollConfiguration.
Usage
Pass aws.preroll as a query parameter in the manifest
request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.preroll=disabled
Or in explicit session initialization, pass it as a top-level field without
the aws. prefix:
POST /v1/session/{hashed-account-id}/{origin-id}/{asset}.m3u8 { "preroll": "disabled" }
Requirements
The following requirements apply to aws.preroll:
-
The playback configuration must have a
LivePreRollConfigurationfor this parameter to have any effect. If no pre-roll is configured, setting this parameter has no effect. -
Applies to HLS live sessions (both SSAI and SGAI).
Behavior
The following table describes how aws.preroll behaves:
| Value | Result |
|---|---|
enabled (or omitted) |
Pre-roll inserted as usual |
disabled |
Pre-roll suppressed for this session |
| Invalid value | Logged as error, treated as enabled |
Limitations
You cannot change this parameter after session initialization.
aws.overlayAvails
When aws.overlayAvails=off, MediaTailor ignores overlay (non-linear)
ad markers in the source manifest and does not insert overlay ads for the
session.
Usage
Pass aws.overlayAvails as a query parameter in the manifest
request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.overlayAvails=off
Requirements
The following requirements apply to
aws.overlayAvails:
-
The source manifest must contain overlay ad markers (for example, SCTE-35 events with overlay segmentation type) for this parameter to have any effect.
-
Applies to HLS and DASH, live and VOD sessions (both SSAI and SGAI).
Behavior
The following table describes how aws.overlayAvails
behaves:
| Value | Result |
|---|---|
on (or omitted) |
Overlay avails are processed and ads inserted as usual |
off |
Overlay ad markers are ignored, no overlay ads inserted |
| Invalid value | Logged as error, treated as not specified (default:
on) |
Limitations
You cannot change this parameter after session initialization.
aws.logMode
When aws.logMode=DEBUG, MediaTailor enables verbose debug logging for
the session. Debug logs are emitted to CloudWatch Logs and provide detailed
information about manifest personalization, ad decision server requests, and
session state – useful for troubleshooting ad insertion issues.
Usage
Pass aws.logMode as a query parameter in the manifest
request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.logMode=DEBUG
Requirements
The following requirements apply to aws.logMode:
-
The playback configuration must have logging enabled (
PercentEnabled > 0orEnabledLoggingStrategiesconfigured) for debug logs to be emitted. -
Debug logging is rate-limited per customer to prevent excessive log volume.
Behavior
The following table describes how aws.logMode
behaves:
| Value | Result |
|---|---|
DEBUG |
Verbose debug logs emitted for the session |
DISABLED (or omitted) |
Normal logging behavior (based on playback configuration settings) |
| Invalid value | Error thrown, session initialization fails |
Limitations
The following limitations apply:
-
You cannot change this parameter after session initialization.
-
Values are case-sensitive (
DEBUG, notdebug).
aws.availSuppressionMode
Controls whether ad avails are suppressed based on their position relative to the live edge. Use this to skip ad breaks that fall within a time window behind or after the live edge – for example, to avoid filling ad breaks that viewers have already passed when joining a live stream mid-event.
Usage
Pass avail suppression parameters as query parameters in the manifest request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.availSuppressionMode=BEHIND_LIVE_EDGE&aws.availSuppressionValue=00:00:10
This parameter works with two companion parameters:
-
aws.availSuppressionValue– The time window (required when mode is notOFF) -
aws.availSuppressionFillPolicy– Controls partial fill behavior (only applies toAFTER_LIVE_EDGEmode)
Requirements
The following requirements apply to avail suppression parameters:
-
Applies to HLS and DASH live sessions.
-
aws.availSuppressionValuemust be provided inHH:MM:SSformat when mode isBEHIND_LIVE_EDGEorAFTER_LIVE_EDGE. -
aws.availSuppressionFillPolicyis only valid when mode isAFTER_LIVE_EDGE.
Mode behavior
The following table describes the effect of each suppression mode:
| Mode | Effect |
|---|---|
OFF (or omitted) |
No avail suppression – all ad breaks are filled normally |
BEHIND_LIVE_EDGE |
Suppress ad breaks that start within the specified time window behind the live edge |
AFTER_LIVE_EDGE |
Suppress ad breaks that start after the specified time window from the live edge |
Fill policy (AFTER_LIVE_EDGE only)
The following table describes the fill policy behavior when mode is
AFTER_LIVE_EDGE:
| Fill policy | Effect |
|---|---|
FULL_AVAIL_ONLY (default) |
Only fill avails that are completely outside the suppression window |
PARTIAL_AVAIL |
Fill the portion of an avail that extends beyond the suppression window |
Example Avail suppression example
The following request suppresses ad breaks within 10 seconds behind the live edge:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.availSuppressionMode=BEHIND_LIVE_EDGE&aws.availSuppressionValue=00:00:10Limitations
The following limitations apply:
-
You cannot change this parameter after session initialization.
-
aws.availSuppressionValuemust not be provided when mode isOFF. -
Invalid time format in
aws.availSuppressionValuecauses mode to fall back toOFF.
aws.contentReserveSeconds
When aws.contentReserveSeconds is present, MediaTailor turns on dynamic
avail sizing for the session and holds back a content reserve of this size, in
seconds. MediaTailor uses the reserve to shorten underfilled ad avails without stalling
the player. For more information, see Dynamic avail sizing.
Usage
Pass aws.contentReserveSeconds as a query parameter in the
manifest request:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.contentReserveSeconds=180
Requirements
The following requirements apply to
aws.contentReserveSeconds:
-
Applies to HLS live and live-to-VOD streams.
-
Applies to server-side ad insertion only, not server-guided ad insertion (SGAI).
-
The reserve can't be larger than the origin manifest window minus 60 seconds. If you request a larger reserve, MediaTailor reduces it to that limit.
Behavior
The following table describes how aws.contentReserveSeconds
behaves:
| Value | Result |
|---|---|
Integer, at least 1 |
Dynamic avail sizing is on, with a content reserve of this size |
| Larger than the origin manifest window minus 60 seconds | Reduced to the origin manifest window minus 60 seconds |
| Omitted | Dynamic avail sizing is off |
Invalid value (for example, less than 1 or not an
integer) |
Session request fails |
Limitations
You cannot change this parameter after session initialization.
aws.maxAvailInflationSeconds
aws.maxAvailInflationSeconds sets the maximum time, in seconds, that
MediaTailor adds to a single ad avail when it inflates that avail to refill the content
reserve. MediaTailor inflates by the smaller of the deficit and this value. For more
information, see Dynamic avail sizing.
Usage
Pass aws.maxAvailInflationSeconds as a query parameter in the
manifest request, together with
aws.contentReserveSeconds:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.contentReserveSeconds=180&aws.maxAvailInflationSeconds=60
Requirements
The following requirements apply to
aws.maxAvailInflationSeconds:
-
This parameter is ignored unless
aws.contentReserveSecondsis present.
Behavior
The following table describes how aws.maxAvailInflationSeconds
behaves:
| Value | Result |
|---|---|
0 |
Inflation is off. The reserve absorbs underfill but doesn't refill. |
1 to 120 |
MediaTailor inflates an avail by the smaller of the deficit and this value |
| Omitted | Default of 120 applies |
Invalid value (outside 0 to 120 or not
an integer) |
Session request fails |
Present without aws.contentReserveSeconds |
Ignored |
Limitations
You cannot change this parameter after session initialization.
aws.replenishmentThresholdSeconds
aws.replenishmentThresholdSeconds sets the minimum deficit, in
seconds, that triggers inflation. The deficit is
aws.contentReserveSeconds minus the current reserve. MediaTailor doesn't
inflate an avail until the deficit reaches this value. If you set it higher than the
deficit your sessions typically reach, MediaTailor never inflates avails. For more
information, see Dynamic avail sizing.
Usage
Pass aws.replenishmentThresholdSeconds as a query parameter in
the manifest request, together with
aws.contentReserveSeconds:
GET /v1/master/{hashed-account-id}/{origin-id}/{asset}.m3u8?aws.contentReserveSeconds=180&aws.maxAvailInflationSeconds=60&aws.replenishmentThresholdSeconds=60
Requirements
The following requirements apply to
aws.replenishmentThresholdSeconds:
-
This parameter is ignored unless
aws.contentReserveSecondsis present.
Behavior
The following table describes how
aws.replenishmentThresholdSeconds behaves:
| Value | Result |
|---|---|
0 |
MediaTailor inflates on any deficit |
1 up to the value of
aws.contentReserveSeconds |
MediaTailor inflates only when the deficit reaches this value |
| Omitted | Default of 0 applies |
Invalid value (negative, greater than
aws.contentReserveSeconds, or not an integer) |
Session request fails |
Present without aws.contentReserveSeconds |
Ignored |
Limitations
You cannot change this parameter after session initialization.