

# 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
<a name="variables-service-supported"></a>

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](#variables-service-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](#variables-service-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](#variables-service-replenishmentthresholdseconds). | 

## aws.startTime
<a name="variables-service-starttime"></a>

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.startTime` cannot 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-TIME` in the source manifest.
+ `EXT-X-START` is a player hint – MediaTailor cannot guarantee all players honor it.

## aws.preroll
<a name="variables-service-preroll"></a>

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 `LivePreRollConfiguration` for 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
<a name="variables-service-overlayavails"></a>

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
<a name="variables-service-logmode"></a>

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 > 0` or `EnabledLoggingStrategies` configured) 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`, not `debug`).

## aws.availSuppressionMode
<a name="variables-service-availsuppression"></a>

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 not `OFF`)
+ `aws.availSuppressionFillPolicy` – Controls partial fill behavior (only applies to `AFTER_LIVE_EDGE` mode)

**Requirements**  
The following requirements apply to avail suppression parameters:
+ Applies to HLS and DASH live sessions.
+ `aws.availSuppressionValue` must be provided in `HH:MM:SS` format when mode is `BEHIND_LIVE_EDGE` or `AFTER_LIVE_EDGE`.
+ `aws.availSuppressionFillPolicy` is only valid when mode is `AFTER_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:10
```

**Limitations**  
The following limitations apply:
+ You cannot change this parameter after session initialization.
+ `aws.availSuppressionValue` must not be provided when mode is `OFF`.
+ Invalid time format in `aws.availSuppressionValue` causes mode to fall back to `OFF`.

## aws.contentReserveSeconds
<a name="variables-service-contentreserveseconds"></a>

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](dynamic-avail-sizing.md).

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


**aws.contentReserveSeconds behavior**  

| 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
<a name="variables-service-maxavailinflationseconds"></a>

`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](dynamic-avail-sizing.md).

**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.contentReserveSeconds` is present.

**Behavior**  
The following table describes how `aws.maxAvailInflationSeconds` behaves:


**aws.maxAvailInflationSeconds behavior**  

| 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
<a name="variables-service-replenishmentthresholdseconds"></a>

`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](dynamic-avail-sizing.md).

**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.contentReserveSeconds` is present.

**Behavior**  
The following table describes how `aws.replenishmentThresholdSeconds` behaves:


**aws.replenishmentThresholdSeconds behavior**  

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