Skip to Content
Mux Docs: Home

API Reference

Welcome to the new Mux Docs.
The old version is still available here

Assets

An asset refers to a piece of media content that is stored or is being live streamed through the Mux system. An asset always has a duration and one or more tracks (audio, video, and text data).

The media content of an asset cannot be updated once created, however an asset can be used to create another asset, and can be modified within that process.

id
string

Unique identifier for the Asset. Max 255 characters.

created_at
string

Time the Asset was created, defined as a Unix timestamp (seconds since epoch).

status
string
Possible values: "preparing""ready""errored"

The status of the asset.

duration
number

The duration of the asset in seconds (max duration for a single asset is 12 hours).

max_stored_resolution
string
Possible values: "Audio only""SD""HD""FHD""UHD"

The maximum resolution that has been stored for the asset. The asset may be delivered at lower resolutions depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored.

max_stored_frame_rate
number

The maximum frame rate that has been stored for the asset. The asset may be delivered at lower frame rates depending on the device and bandwidth, however it cannot be delivered at a higher value than is stored. This field may return -1 if the frame rate of the input cannot be reliably determined.

aspect_ratio
string

The aspect ratio of the asset in the form of width:height, for example 16:9.

playback_ids
array

An array of Playback ID objects. Use these to create HLS playback URLs. See Play your videos for more details.

playback_ids[]id
string

Unique identifier for the PlaybackID

playback_ids[]policy
string
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

tracks
array

The individual media tracks that make up an asset.

tracks[]id
string

Unique identifier for the Track

tracks[]type
string
Possible values: "video""audio""text"

The type of track

tracks[]duration
number

The duration in seconds of the track media. This parameter is not set for text type tracks. This field is optional and may not be set. The top level duration field of an asset will always be set.

tracks[]max_width
integer

The maximum width in pixels available for the track. Only set for the video type track.

tracks[]max_height
integer

The maximum height in pixels available for the track. Only set for the video type track.

tracks[]max_frame_rate
number

The maximum frame rate available for the track. Only set for the video type track. This field may return -1 if the frame rate of the input cannot be reliably determined.

tracks[]max_channels
integer

The maximum number of audio channels the track supports. Only set for the audio type track.

tracks[]max_channel_layout
string

Only set for the audio type track.

tracks[]text_type
string
Possible values: "subtitles"

This parameter is only set for text type tracks.

tracks[]text_source
string
Possible values: "uploaded""embedded""generated_live""generated_live_final"

The source of the text contained in a Track of type text. Valid text_source values are listed below.

  • uploaded: Tracks uploaded to Mux as caption or subtitle files using the Create Asset Track API.
  • embedded: Tracks extracted from an embedded stream of CEA-608 closed captions.
  • generated_live: Tracks generated by automatic speech recognition on a live stream configured with generated_subtitles. If an Asset has both generated_live and generated_live_final tracks that are ready, then only the generated_live_final track will be included during playback.
  • generated_live_final: Tracks generated by automatic speech recognition on a live stream using generated_subtitles. The accuracy, timing, and formatting of these subtitles is improved compared to the corresponding generated_live tracks. However, generated_live_final tracks will not be available in ready status until the live stream ends. If an Asset has both generated_live and generated_live_final tracks that are ready, then only the generated_live_final track will be included during playback.
tracks[]language_code
string

The language code value represents BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is only set for text type and subtitles text type tracks.

tracks[]name
string

The name of the track containing a human-readable description. The hls manifest will associate a subtitle text track with this value. For example, the value is "English" for subtitles text track for the language_code value of en-US. This parameter is only set for text type and subtitles text type tracks.

tracks[]closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This parameter is only set for text type and subtitles text type tracks.

tracks[]passthrough
string

Arbitrary user-supplied metadata set for the track either when creating the asset or track. This parameter is only set for text type tracks. Max 255 characters.

tracks[]status
string
Possible values: "preparing""ready""errored"

The status of the track. This parameter is only set for text type tracks.

errors
object

Object that describes any errors that happened when processing this asset.

errorstype
string

The type of error that occurred for this asset.

errorsmessages
array

Error messages with more details.

upload_id
string

Unique identifier for the Direct Upload. This is an optional parameter added when the asset is created from a direct upload.

is_live
boolean

Indicates whether the live stream that created this asset is currently active and not in idle state. This is an optional parameter added when the asset is created from a live stream.

passthrough
string

Arbitrary user-supplied metadata set for the asset. Max 255 characters.

live_stream_id
string

Unique identifier for the live stream. This is an optional parameter added when the asset is created from a live stream.

master
object

An object containing the current status of Master Access and the link to the Master MP4 file when ready. This object does not exist if master_acess is set to none and when the temporary URL expires.

masterstatus
string
Possible values: "ready""preparing""errored"
masterurl
string

The temporary URL to the master version of the video, as an MP4 file. This URL will expire after 24 hours.

master_access
string (default: none)
Possible values: "temporary""none"
mp4_support
string (default: none)
Possible values: "standard""none"
source_asset_id
string

Asset Identifier of the video used as the source for creating the clip.

normalize_audio
boolean (default: false)

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

static_renditions
object

An object containing the current status of any static renditions (mp4s). The object does not exist if no static renditions have been requested. See Download your videos for more information.

static_renditionsstatus
string (default: disabled)
Possible values: "ready""preparing""disabled""errored"

Indicates the status of downloadable MP4 versions of this asset.

static_renditionsfiles
array

Array of file objects.

static_renditionsfiles[]name
string
Possible values: "low.mp4""medium.mp4""high.mp4""audio.m4a"
static_renditionsfiles[]ext
string
Possible values: "mp4""m4a"

Extension of the static rendition file

static_renditionsfiles[]height
integer

The height of the static rendition's file in pixels

static_renditionsfiles[]width
integer

The width of the static rendition's file in pixels

static_renditionsfiles[]bitrate
integer

The bitrate in bits per second

static_renditionsfiles[]filesize
string

The file size in bytes

recording_times
array

An array of individual live stream recording sessions. A recording session is created on each encoder connection during the live stream. Additionally any time slate media is inserted during brief interruptions in the live stream media or times when the live streaming software disconnects, a recording session representing the slate media will be added with a "slate" type.

recording_times[]started_at
string

The time at which the recording for the live stream started. The time value is Unix epoch time represented in ISO 8601 format.

recording_times[]duration
number

The duration of the live stream recorded. The time value is in seconds.

recording_times[]typeBeta
string
Possible values: "content""slate"

The type of media represented by the recording session, either content for normal stream content or slate for slate media inserted during stream interruptions.

non_standard_input_reasons
object

An object containing one or more reasons the input file is non-standard. See the guide on minimizing processing time for more information on what a standard input is defined as. This object only exists on on-demand assets that have non-standard inputs, so if missing you can assume the input qualifies as standard.

non_standard_input_reasonsvideo_codec
string

The video codec used on the input file. For example, the input file encoded with hevc video codec is non-standard and the value of this parameter is hevc.

non_standard_input_reasonsaudio_codec
string

The audio codec used on the input file. Non-AAC audio codecs are non-standard.

non_standard_input_reasonsvideo_gop_size
string
Possible values: "high"

The video key frame Interval (also called as Group of Picture or GOP) of the input file is high. This parameter is present when the gop is greater than 20 seconds.

non_standard_input_reasonsvideo_frame_rate
string

The video frame rate of the input file. Video with average frames per second (fps) less than 5 or greater than 120 is non-standard. A -1 frame rate value indicates Mux could not determine the frame rate of the video track.

non_standard_input_reasonsvideo_resolution
string

The video resolution of the input file. Video resolution higher than 2048 pixels on any one dimension (height or width) is considered non-standard, The resolution value is presented as width x height in pixels.

non_standard_input_reasonsvideo_bitrate
string
Possible values: "high"

The video bitrate of the input file is high. This parameter is present when the average bitrate of any key frame interval (also known as Group of Pictures or GOP) is higher than what's considered standard which typically is 16 Mbps.

non_standard_input_reasonspixel_aspect_ratio
string

The video pixel aspect ratio of the input file.

non_standard_input_reasonsvideo_edit_list
string
Possible values: "non-standard"

Video Edit List reason indicates that the input file's video track contains a complex Edit Decision List.

non_standard_input_reasonsaudio_edit_list
string
Possible values: "non-standard"

Audio Edit List reason indicates that the input file's audio track contains a complex Edit Decision List.

non_standard_input_reasonsunexpected_media_file_parameters
string
Possible values: "non-standard"

A catch-all reason when the input file in created with non-standard encoding parameters.

test
boolean

True means this live stream is a test asset. A test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test assets are watermarked with the Mux logo, limited to 10 seconds, and deleted after 24 hrs.

Create an asset
post

Create a new Mux Video asset.

curl https://api.mux.com/video/v1/assets \
  -X POST \
  -d '{ "input": "https://muxed.s3.amazonaws.com/leds.mp4", "playback_policy": ["public"] }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The URL of the file that Mux should download and use.

  • For subtitles text tracks, the URL is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the URL is the location of the watermark image.
  • When creating clips from existing Mux assets, the URL is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.

An object that describes how the image file referenced in URL should be placed over the video (i.e. watermarking). Ensure that the URL is active and persists the entire lifespan of the video object.

vertical_align
string
Possible values: "top""middle""bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left""center""right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video""audio""text"

This parameter is required for text type tracks.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text type tracks.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type tracks. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

passthrough
string

Arbitrary user-supplied metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none""standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean
(default: false)

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none""temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

post
201
/video/v1/assets
Request
(application/json)
{
  "input": [
    {
      "url": "https://muxed.s3.amazonaws.com/leds.mp4"
    }
  ],
  "playback_policy": [
    "public"
  ]
}
Response
(application/json)
{
  "data": {
    "status": "preparing",
    "playback_ids": [
      {
        "policy": "public",
        "id": "uNbxnGLKJ00yfbijDO8COxTOyVKT01xpxW"
      }
    ],
    "mp4_support": "none",
    "master_access": "none",
    "id": "SqQnqz6s5MBuXGvJaUWdXuXM93J9Q2yv",
    "created_at": "1607452572"
  }
}
List assets
get

List all Mux assets.

curl https://api.mux.com/video/v1/assets \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

live_stream_id
string

Filter response to return all the assets for this live stream only

upload_id
string

Filter response to return an asset created from this direct upload only

get
200
/video/v1/assets
Response
(application/json)
{
  "data": [
    {
      "tracks": [
        {
          "type": "video",
          "max_width": 1920,
          "max_height": 800,
          "max_frame_rate": 24,
          "id": "HK01Bq7FrEQmIu3QpRiZZ98HQOOZjm6BYyg17eEunlyo",
          "duration": 734.166667
        },
        {
          "type": "audio",
          "max_channels": 2,
          "max_channel_layout": "stereo",
          "id": "nNKHJqw2G9cE019AoK16CJr3O27gGnbtW4w525hJWqWw",
          "duration": 734.143991
        }
      ],
      "status": "ready",
      "playback_ids": [
        {
          "policy": "public",
          "id": "85g23gYz7NmQu02YsY81ihuod6cZMxCp017ZrfglyLCKc"
        }
      ],
      "mp4_support": "none",
      "max_stored_resolution": "HD",
      "max_stored_frame_rate": 24,
      "master_access": "none",
      "id": "8jd7M77xQgf2NzuocJRPYdSdEfY5dLlcRwFARtgQqU4",
      "duration": 734.25,
      "created_at": "1609869152",
      "aspect_ratio": "12:5"
    },
    {
      "tracks": [
        {
          "type": "video",
          "max_width": 1920,
          "max_height": 1080,
          "max_frame_rate": 29.97,
          "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
          "duration": 23.8238
        },
        {
          "type": "audio",
          "max_channels": 2,
          "max_channel_layout": "stereo",
          "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
          "duration": 23.823792
        }
      ],
      "status": "ready",
      "playback_ids": [
        {
          "policy": "public",
          "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
        }
      ],
      "mp4_support": "none",
      "max_stored_resolution": "HD",
      "max_stored_frame_rate": 29.97,
      "master_access": "none",
      "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
      "duration": 23.857167,
      "created_at": "1609868768",
      "aspect_ratio": "16:9"
    }
  ]
}
Retrieve an asset
get

Retrieves the details of an asset that has previously been created. Supply the unique asset ID that was returned from your previous request, and Mux will return the corresponding asset information. The same information is returned when creating an asset.

curl https://api.mux.com/video/v1/assets/${ASSET_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

get
200
/video/v1/assets/{ASSET_ID}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "playback_ids": [
      {
        "policy": "public",
        "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
      }
    ],
    "mp4_support": "none",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "none",
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Delete an asset
del

Deletes a video asset and all its data.

curl https://api.mux.com/video/v1/assets/${ASSET_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

del
204
/video/v1/assets/{ASSET_ID}
Update an Asset
patch

Updates the details of an already-created Asset with the provided Asset ID. This currently supports only the passthrough field.

Request body params
passthrough
string

Arbitrary metadata set for the Asset. Max 255 characters. In order to clear this value, the field should be included with an empty string value.

Request path & query params
ASSET_ID
string

The asset ID.

patch
200
/video/v1/assets/{ASSET_ID}
Request
(application/json)
{
  "passthrough": "Example"
}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "playback_ids": [
      {
        "policy": "public",
        "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
      }
    ],
    "mp4_support": "none",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "none",
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "updated_at": "1609869000",
    "aspect_ratio": "16:9",
    "passthrough": "Example"
  }
}
Retrieve asset input info
get

Returns a list of the input objects that were used to create the asset along with any settings that were applied to each input.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/input-info \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

get
200
/video/v1/assets/{ASSET_ID}/input-info
Response
(application/json)
{
  "data": [
    {
      "settings": {
        "url": "https://muxed.s3.amazonaws.com/leds.mp4"
      },
      "file": {
        "container_format": "mp4",
        "tracks": [
          {
            "type": "video",
            "duration": 120,
            "width": 1280,
            "height": 720,
            "frame_rate": 30,
            "encoding": "h.264"
          },
          {
            "type": "audio",
            "duration": 120,
            "sample_rate": 16000,
            "sample_size": 24,
            "encoding": "aac"
          }
        ]
      }
    },
    {
      "settings": {
        "url": "https://example.com/myVideo_en.srt"
      },
      "file": {
        "container_format": "srt"
      }
    }
  ]
}
Create a playback ID
post

Creates a playback ID that can be used to stream the asset to a viewer.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids \
  -X POST \
  -d '{ "policy": "public" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
policy
string
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Request path & query params
ASSET_ID
string

The asset ID.

post
201
/video/v1/assets/{ASSET_ID}/playback-ids
Request
(application/json)
{
  "policy": "public"
}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
  }
}
Retrieve a playback ID
get

Retrieves information about the specified playback ID.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids/${PLAYBACK_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

PLAYBACK_ID
string

The live stream's playback ID.

get
200
/video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "vAFLI2eKFFicXX00iHBS2vqt5JjJGg5HV6fQ4Xijgt1I"
  }
}
Delete a playback ID
del

Deletes a playback ID, rendering it nonfunctional for viewing an asset's video content. Please note that deleting the playback ID removes access to the underlying asset; a viewer who started playback before the playback ID was deleted may be able to watch the entire video for a limited duration.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/playback-ids/${PLAYBACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

PLAYBACK_ID
string

The live stream's playback ID.

del
204
/video/v1/assets/{ASSET_ID}/playback-ids/{PLAYBACK_ID}
Update MP4 support
put

Allows you to add or remove mp4 support for assets that were created without it. Currently there are two values supported in this request, standard and none. none means that an asset does not have mp4 support, so submitting a request with mp4_support set to none will delete the mp4 assets from the asset in question.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/mp4-support \
  -X PUT \
  -d '{ "mp4_support": "standard" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
mp4_support
string
Possible values: "standard""none"

String value for the level of mp4 support

Request path & query params
ASSET_ID
string

The asset ID.

put
200
/video/v1/assets/{ASSET_ID}/mp4-support
Request
(application/json)
{
  "mp4_support": "standard"
}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "static_renditions": {
      "status": "preparing"
    },
    "playback_ids": [
      {
        "policy": "public",
        "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
      }
    ],
    "mp4_support": "standard",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "none",
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Update master access
put

Allows you to add temporary access to the master (highest-quality) version of the asset in MP4 format. A URL will be created that can be used to download the master version for 24 hours. After 24 hours Master Access will revert to "none". This master version is not optimized for web and not meant to be streamed, only downloaded for purposes like archiving or editing the video offline.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/master-access \
  -X PUT \
  -d '{ "master_access": "temporary" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
master_access
string
Possible values: "temporary""none"

Add or remove access to the master version of the video.

Request path & query params
ASSET_ID
string

The asset ID.

put
200
/video/v1/assets/{ASSET_ID}/master-access
Request
(application/json)
{
  "master_access": "temporary"
}
Response
(application/json)
{
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1920,
        "max_height": 1080,
        "max_frame_rate": 29.97,
        "id": "RiyQPM31a1SPtfI802bEP2zD02F5FQVNL801FRHeE5t01G4",
        "duration": 23.8238
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "LvINTciHVoC017knMCH01y9pSi5OrDLCRaBPNDAoNJcmg",
        "duration": 23.823792
      }
    ],
    "status": "ready",
    "playback_ids": [
      {
        "policy": "public",
        "id": "Lj02VZDorh9hCV00flNqPli8fmwf6KEppug01w8zDEYVlQ"
      }
    ],
    "mp4_support": "none",
    "max_stored_resolution": "HD",
    "max_stored_frame_rate": 29.97,
    "master_access": "temporary",
    "master": {
      "status": "preparing"
    },
    "id": "lJ4bGGsp7ZlPf02nMg015W02iHQLN9XnuuLRBsPS00xqd68",
    "duration": 23.857167,
    "created_at": "1609868768",
    "aspect_ratio": "16:9"
  }
}
Create an asset track
post

Adds an asset track (for example, subtitles) to an asset.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/tracks \
  -X POST \
  -d '{ "url": "https://example.com/myVIdeo_en.srt", "type": "text", "text_type": "subtitles", "closed_captions": true, "language_code": "en-US", "name": "English",  "passthrough": "English" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
url
string
type
string
Possible values: "text"
text_type
string
Possible values: "subtitles"
language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English.

name
string

The name of the track containing a human-readable description. This value must be unique across all the text type and subtitles text type tracks. HLS manifest will associate subtitle text track with this value. For example, set the value to "English" for subtitles text track with language_code as en-US. If this parameter is not included, Mux will auto-populate based on the language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH).

passthrough
string

Arbitrary user-supplied metadata set for the track either when creating the asset or track.

Request path & query params
ASSET_ID
string

The asset ID.

post
201
/video/v1/assets/{ASSET_ID}/tracks
Request
(application/json)
{
  "url": "https://example.com/myVideo_en.srt",
  "type": "text",
  "text_type": "subtitles",
  "language_code": "en-US",
  "name": "English",
  "closed_captions": true,
  "passthrough": "English"
}
Response
(application/json)
{
  "data": {
    "type": "text",
    "text_type": "subtitles",
    "status": "preparing",
    "passthrough": "English",
    "name": "English",
    "language_code": "en-US",
    "id": "xBe7u01029ipxBLQhYzZCJ1cke01zCkuUsgnYtH0017nNzbpv2YcsoMDmw",
    "closed_captions": true
  }
}
Delete an asset track
del

Removes a text track from an asset. Audio and video tracks on assets cannot be removed.

curl https://api.mux.com/video/v1/assets/${ASSET_ID}/tracks/${TRACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
ASSET_ID
string

The asset ID.

TRACK_ID
string

The track ID.

del
204
/video/v1/assets/{ASSET_ID}/tracks/{TRACK_ID}

Live Streams

A Live Stream represents a unique live stream of video being pushed to Mux. It includes configuration details (a Stream Key) for live broadcasting software/hardware and a Playback ID for playing the stream anywhere. Currently, RTMP is the only supported method of ingesting video. Use rtmp://global-live.mux.com:5222/app with the Live Stream's Stream Key for getting the video into Mux, and use https://stream.mux.com with the Live Stream's Playback ID for playback.

A Live Stream can be used once for a specific event, or re-used forever. If you're building an application like Facebook Live or Twitch, you could create one Live Stream per user. This allows them to configure their broadcasting software once, and the Live Stream Playback ID will always show their latest stream.

Each RTMP session creates a new video asset automatically. You can set up a webhook to be notified each time a broadcast (or Live Stream RTMP session) begins or ends with the video.live_stream.active and video.live_stream.idle events respectively. Assets that are created from a Live Stream have the same behavior as other Assets you create.

Learn more about how to go live in our guides.

id
string

Unique identifier for the Live Stream. Max 255 characters.

created_at
string

Time the Live Stream was created, defined as a Unix timestamp (seconds since epoch).

stream_key
string

Unique key used for streaming to a Mux RTMP endpoint. This should be considered as sensitive as credentials, anyone with this stream key can begin streaming.

active_asset_id
string

The Asset that is currently being created if there is an active broadcast.

recent_asset_ids
array

An array of strings with the most recent Assets that were created from this live stream.

status
string
Possible values: "active""idle""disabled"

idle indicates that there is no active broadcast. active indicates that there is an active broadcast and disabled status indicates that no future RTMP streams can be published.

playback_ids
array

An array of Playback ID objects. Use these to create HLS playback URLs. See Play your videos for more details.

playback_ids[]id
string

Unique identifier for the PlaybackID

playback_ids[]policy
string
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

new_asset_settings
object

The settings to be used when creating a new asset. You can use any of the usual settings when creating an asset normally, with the exception to not include file url for creating the asset in input. You could optionally add overlay_setting and input urls to add Subtitles / Captions.

passthrough
string

Arbitrary user-supplied metadata set for the asset. Max 255 characters.

audio_only
boolean

The live stream only processes the audio track if the value is set to true. Mux drops the video track if broadcasted.

embedded_subtitles
array

Describes the embedded closed caption configuration of the incoming live stream.

embedded_subtitles[]name
string

A name for this live stream closed caption track.

embedded_subtitles[]passthrough
string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

embedded_subtitles[]language_code
string (default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

embedded_subtitles[]language_channel
string (default: cc1)
Possible values: "cc1"

CEA-608 caption channel to read data from.

generated_subtitles
array

Configure the incoming live stream to include subtitles created with automatic speech recognition. Each Asset created from a live stream with generated_subtitles configured will automatically receive two text tracks. The first of these will have a text_source value of generated_live, and will be available with ready status as soon as the stream is live. The second text track will have a text_source value of generated_live_final and will contain subtitles with improved accuracy, timing, and formatting. However, generated_live_final tracks will not be available in ready status until the live stream ends. If an Asset has both generated_live and generated_live_final tracks that are ready, then only the generated_live_final track will be included during playback.

generated_subtitles[]name
string

A name for this live stream subtitle track.

generated_subtitles[]passthrough
string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

generated_subtitles[]language_code
string (default: en)
Possible values: "en""en-US"

The language to generate subtitles in.

generated_subtitles[]transcription_vocabulary_ids
array

Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included.

reconnect_window
number (default: 60, minimum: 0, maximum: 1800)

When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. Max: 1800s (30 minutes).

Reduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the use_slate_for_standard_latency option.

use_slate_for_standard_latency
boolean (default: false)

By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream.

reconnect_slate_url
string

The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. If this is not set, the default slate media will be used.

reduced_latencyDeprecated
boolean

This field is deprecated. Please use latency_mode instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this if you want lower latency for your live stream. See the Reduce live stream latency guide to understand the tradeoffs.

simulcast_targets
array

Each Simulcast Target contains configuration details to broadcast (or "restream") a live stream to a third-party streaming service. See the Stream live to 3rd party platforms guide.

simulcast_targets[]id
string

ID of the Simulcast Target

simulcast_targets[]passthrough
string

Arbitrary user-supplied metadata set when creating a simulcast target.

simulcast_targets[]status
string
Possible values: "idle""starting""broadcasting""errored"

The current status of the simulcast target. See Statuses below for detailed description.

  • idle: Default status. When the parent live stream is in disconnected status, simulcast targets will be idle state.
  • starting: The simulcast target transitions into this state when the parent live stream transition into connected state.
  • broadcasting: The simulcast target has successfully connected to the third party live streaming service and is pushing video to that service.
  • errored: The simulcast target encountered an error either while attempting to connect to the third party live streaming service, or mid-broadcasting. Compared to other errored statuses in the Mux Video API, a simulcast may transition back into the broadcasting state if a connection with the service can be re-established.
simulcast_targets[]stream_key
string

Stream Key represents an stream identifier for the third party live streaming service to simulcast the parent live stream too.

simulcast_targets[]url
string

RTMP hostname including the application name for the third party live streaming service.

latency_modeBeta
string
Possible values: "low""reduced""standard"

Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags. The Low Latency value is a beta feature. Read more here: https://mux.com/blog/introducing-low-latency-live-streaming/

test
boolean

True means this live stream is a test live stream. Test live streams can be used to help evaluate the Mux Video APIs for free. There is no limit on the number of test live streams, but they are watermarked with the Mux logo, and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours.

max_continuous_duration
integer (default: 43200, minimum: 60, maximum: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

Create a live stream
post

Creates a new live stream. Once created, an encoder can connect to Mux via the specified stream key and begin streaming to an audience.

curl https://api.mux.com/video/v1/live-streams \
  -X POST \
  -d '{ "playback_policy": "public", "new_asset_settings": { "playback_policy": "public" } }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
playback_policy
array
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The URL of the file that Mux should download and use.

  • For subtitles text tracks, the URL is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the URL is the location of the watermark image.
  • When creating clips from existing Mux assets, the URL is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.

An object that describes how the image file referenced in URL should be placed over the video (i.e. watermarking). Ensure that the URL is active and persists the entire lifespan of the video object.

vertical_align
string
Possible values: "top""middle""bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left""center""right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video""audio""text"

This parameter is required for text type tracks.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text type tracks.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type tracks. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

passthrough
string

Arbitrary user-supplied metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none""standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean
(default: false)

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none""temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

reconnect_window
number
(default: 60, min: 0, max: 1800)

When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset. Defaults to 60 seconds on the API if not specified.

Reduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the use_slate_for_standard_latency option.

use_slate_for_standard_latency
boolean
(default: false)

By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream.

reconnect_slate_url
string

The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. If this is not set, the default slate media will be used.

passthrough
string
audio_only
boolean

Force the live stream to only process the audio track when the value is set to true. Mux drops the video track if broadcasted.

Describe the embedded closed caption contents of the incoming live stream.

name
string

A name for this live stream closed caption track.

passthrough
string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

language_code
string
(default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

language_channel
string
(default: cc1)
Possible values: "cc1"

CEA-608 caption channel to read data from.

Configure the incoming live stream to include subtitles created with automatic speech recognition. Each Asset created from a live stream with generated_subtitles configured will automatically receive two text tracks. The first of these will have a text_source value of generated_live, and will be available with ready status as soon as the stream is live. The second text track will have a text_source value of generated_live_final and will contain subtitles with improved accuracy, timing, and formatting. However, generated_live_final tracks will not be available in ready status until the live stream ends. If an Asset has both generated_live and generated_live_final tracks that are ready, then only the generated_live_final track will be included during playback.

name
string

A name for this live stream subtitle track.

passthrough
string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

language_code
string
(default: en)
Possible values: "en""en-US"

The language to generate subtitles in.

transcription_vocabulary_ids
array

Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included.

reduced_latency
boolean
Deprecated

This field is deprecated. Please use latency_mode instead. Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this if you want lower latency for your live stream. Read more here: https://mux.com/blog/reduced-latency-for-mux-live-streaming-now-available/

latency_mode
string
Beta
Possible values: "low""reduced""standard"

Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags. The Low Latency value is a beta feature. Read more here: https://mux.com/blog/introducing-low-latency-live-streaming/

test
boolean

Marks the live stream as a test live stream when the value is set to true. A test live stream can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test live streams created. Test live streams are watermarked with the Mux logo and limited to 5 minutes. The test live stream is disabled after the stream is active for 5 mins and the recorded asset also deleted after 24 hours.

passthrough
string

Arbitrary user-supplied metadata set by you when creating a simulcast target.

stream_key
string

Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to.

url
string

RTMP hostname including application name for the third party live streaming service. Example: rtmp://live.example.com/app.

max_continuous_duration
integer
(default: 43200, min: 60, max: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

post
201
/video/v1/live-streams
Request
(application/json)
{
  "playback_policy": [
    "public"
  ],
  "new_asset_settings": {
    "playback_policy": [
      "public"
    ]
  }
}
Response
(application/json)
{
  "data": {
    "stream_key": "abcdefgh",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "latency_mode": "standard",
    "max_continuous_duration": 43200
  }
}
List live streams
get

Lists the live streams that currently exist in the current environment.

curl https://api.mux.com/video/v1/live-streams \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

stream_key
string

Filter response to return live stream for this stream key only

status
string
Possible values: "active""idle""disabled"

Filter response to return live streams with the specified status only. idle indicates that there is no active broadcast. active indicates that there is an active broadcast and disabled status indicates that no future RTMP streams can be published.

get
200
/video/v1/live-streams
Response
(application/json)
{
  "data": [
    {
      "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481",
      "status": "idle",
      "reconnect_window": 60,
      "playback_ids": [
        {
          "policy": "public",
          "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
        }
      ],
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ]
      },
      "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
      "created_at": "1609937654",
      "latency_mode": "standard",
      "max_continuous_duration": 43200
    },
    {
      "stream_key": "d273c65e-1fc8-27dc-e9ef-56144cbceb3a",
      "status": "idle",
      "reconnect_window": 60,
      "recent_asset_ids": [
        "SZs02xxHgYdkHp00OSCjJiHUHqzVQZNU332XPXRxe341o",
        "e4J9cwb5tjVxMeeV8201dC00i800ThPKKGT2SEN002dHH2s"
      ],
      "playback_ids": [
        {
          "policy": "public",
          "id": "00zOcribkUmXqXHzBTpflk2771BRTcKATqPjWf7JHpuM"
        }
      ],
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ]
      },
      "id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc",
      "created_at": "1607587513",
      "latency_mode": "standard",
      "max_continuous_duration": 43200
    }
  ]
}
Retrieve a live stream
get

Retrieves the details of a live stream that has previously been created. Supply the unique live stream ID that was returned from your previous request, and Mux will return the corresponding live stream information. The same information is returned when creating a live stream.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

get
200
/video/v1/live-streams/{LIVE_STREAM_ID}
Response
(application/json)
{
  "data": {
    "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "latency_mode": "standard",
    "max_continuous_duration": 43200
  }
}
Delete a live stream
del

Deletes a live stream from the current environment. If the live stream is currently active and being streamed to, ingest will be terminated and the encoder will be disconnected.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}
Update a live stream
patch

Updates the parameters of a previously-created live stream. This currently supports a subset of variables. Supply the live stream ID and the updated parameters and Mux will return the corresponding live stream information. The information returned will be the same after update as for subsequent get live stream requests.

Request body params
passthrough
string

Arbitrary user-supplied metadata set for the live stream. Max 255 characters. In order to clear this value, the field should be included with an empty-string value.

latency_mode
string
Possible values: "low""reduced""standard"

Latency is the time from when the streamer transmits a frame of video to when you see it in the player. Set this as an alternative to setting low latency or reduced latency flags. The Low Latency value is a beta feature. Read more here: https://mux.com/blog/introducing-low-latency-live-streaming/

reconnect_window
number
(default: 60, min: 0, max: 1800)

When live streaming software disconnects from Mux, either intentionally or due to a drop in the network, the Reconnect Window is the time in seconds that Mux should wait for the streaming software to reconnect before considering the live stream finished and completing the recorded asset.

Reduced and Low Latency streams with a Reconnect Window greater than zero will insert slate media into the recorded asset while waiting for the streaming software to reconnect or when there are brief interruptions in the live stream media. When using a Reconnect Window setting higher than 60 seconds with a Standard Latency stream, we highly recommend enabling slate with the use_slate_for_standard_latency option.

use_slate_for_standard_latency
boolean
(default: false)

By default, Standard Latency live streams do not have slate media inserted while waiting for live streaming software to reconnect to Mux. Setting this to true enables slate insertion on a Standard Latency stream.

reconnect_slate_url
string

The URL of the image file that Mux should download and use as slate media during interruptions of the live stream media. This file will be downloaded each time a new recorded asset is created from the live stream. Set this to a blank string to clear the value so that the default slate media will be used.

max_continuous_duration
integer
(default: 43200, min: 60, max: 43200)

The time in seconds a live stream may be continuously active before being disconnected. Defaults to 12 hours.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

patch
200
/video/v1/live-streams/{LIVE_STREAM_ID}
Request
(application/json)
{
  "latency_mode": "standard",
  "reconnect_window": 30,
  "max_continuous_duration": 1200
}
Response
(application/json)
{
  "data": {
    "stream_key": "831b5bde-cd8a-5bc4-115d-4ba34b19f481",
    "status": "idle",
    "reconnect_window": 30,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "latency_mode": "standard",
    "max_continuous_duration": 1200
  }
}
Create a live stream playback ID
post

Create a new playback ID for this live stream, through which a viewer can watch the streamed content of the live stream.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/playback-ids \
  -X POST \
  -d '{ "policy": "public" }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
policy
string
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids
Request
(application/json)
{
  "policy": "signed"
}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
  }
}
Retrieve a live stream playback ID
get

Fetches information about a live stream's playback ID, through which a viewer can watch the streamed content from this live stream.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

PLAYBACK_ID
string

The live stream's playback ID.

get
200
/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids/{PLAYBACK_ID}
Response
(application/json)
{
  "data": {
    "policy": "public",
    "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
  }
}
Delete a live stream playback ID
del

Deletes the playback ID for the live stream. This will not disable ingest (as the live stream still exists). New attempts to play back the live stream will fail immediately. However, current viewers will be able to continue watching the stream for some period of time.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/playback-ids/${PLAYBACK_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

PLAYBACK_ID
string

The live stream's playback ID.

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}/playback-ids/{PLAYBACK_ID}
Reset a live stream's stream key
post

Reset a live stream key if you want to immediately stop the current stream key from working and create a new stream key that can be used for future broadcasts.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/reset-stream-key \
  -X POST \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/reset-stream-key
Response
(application/json)
{
  "data": {
    "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      },
      {
        "policy": "public",
        "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "latency_mode": "standard",
    "max_continuous_duration": 43200
  }
}
Signal a live stream is finished
put

(Optional) End the live stream recording immediately instead of waiting for the reconnect_window. EXT-X-ENDLIST tag is added to the HLS manifest which notifies the player that this live stream is over.

Mux does not close the encoder connection immediately. Encoders are often configured to re-establish connections immediately which would result in a new recorded asset. For this reason, Mux waits for 60s before closing the connection with the encoder. This 60s timeframe is meant to give encoder operators a chance to disconnect from their end.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/complete \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/complete
Response
(application/json)
{
  "data": {}
}
Disable a live stream
put

Disables a live stream, making it reject incoming RTMP streams until re-enabled. The API also ends the live stream recording immediately when active. Ending the live stream recording adds the EXT-X-ENDLIST tag to the HLS manifest which notifies the player that this live stream is over.

Mux also closes the encoder connection immediately. Any attempt from the encoder to re-establish connection will fail till the live stream is re-enabled.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/disable \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/disable
Response
(application/json)
{
  "data": {}
}
Enable a live stream
put

Enables a live stream, allowing it to accept an incoming RTMP stream.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/enable \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/enable
Response
(application/json)
{
  "data": {}
}
Update a live stream's embedded subtitles
put

Configures a live stream to receive embedded closed captions. The resulting Asset's subtitle text track will have closed_captions: true set.

Request body params

Describe the embedded closed caption contents of the incoming live stream.

name
string

A name for this live stream closed caption track.

passthrough
string

Arbitrary user-supplied metadata set for the live stream closed caption track. Max 255 characters.

language_code
string
(default: en)

The language of the closed caption stream. Value must be BCP 47 compliant.

language_channel
string
(default: cc1)
Possible values: "cc1"

CEA-608 caption channel to read data from.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/embedded-subtitles
Request
(application/json)
{
  "embedded_subtitles": [
    {
      "passthrough": "Example"
    }
  ]
}
Response
(application/json)
{
  "data": {
    "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      },
      {
        "policy": "public",
        "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "embedded_subtitles": [
      {
        "name": "English CC",
        "language_code": "en",
        "language_channel": "cc1",
        "passthrough": "Example"
      }
    ],
    "latency_mode": "standard",
    "max_continuous_duration": 43200
  }
}
Update a live stream's generated subtitles
put

Updates a live stream's automatic-speech-recognition-generated subtitle configuration. Automatic speech recognition subtitles can be removed by sending an empty array in the request payload.

Request body params

Update automated speech recognition subtitle configuration for a live stream. At most one subtitle track is allowed.

name
string

A name for this live stream subtitle track.

passthrough
string

Arbitrary metadata set for the live stream subtitle track. Max 255 characters.

language_code
string
(default: en)
Possible values: "en""en-US"

The language to generate subtitles in.

transcription_vocabulary_ids
array

Unique identifiers for existing Transcription Vocabularies to use while generating subtitles for the live stream. If the Transcription Vocabularies provided collectively have more than 1000 phrases, only the first 1000 phrases will be included.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

put
200
/video/v1/live-streams/{LIVE_STREAM_ID}/generated-subtitles
Request
(application/json)
{
  "generated_subtitles": [
    {
      "name": "English CC (ASR)",
      "language": "en",
      "passthrough": "Example"
    }
  ]
}
Response
(application/json)
{
  "data": {
    "stream_key": "acaf2ca1-ba9c-5ffe-8c9c-a02bbf0009a6",
    "status": "idle",
    "reconnect_window": 60,
    "playback_ids": [
      {
        "policy": "public",
        "id": "HNRDuwff3K2VjTZZAPuvd2Kx6D01XUQFv02GFBHPUka018"
      },
      {
        "policy": "public",
        "id": "4O902oOPU100s7XIQgOeY01U7dHzYlBe26zi3Sq01EJqnxw"
      }
    ],
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ]
    },
    "id": "ZEBrNTpHC02iUah025KM3te6ylM7W4S4silsrFtUkn3Ag",
    "created_at": "1609937654",
    "generated_subtitles": [
      {
        "name": "English CC (ASR)",
        "language_code": "en",
        "passthrough": "Example"
      }
    ]
  }
}
Create a live stream simulcast target
post

Create a simulcast target for the parent live stream. Simulcast target can only be created when the parent live stream is in idle state. Only one simulcast target can be created at a time with this API.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets \
  -X POST \
  -d '{"url": "rtmp://live.example.com/app", "stream_key": "abcdefgh", "passthrough":"Example"}' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
passthrough
string

Arbitrary user-supplied metadata set by you when creating a simulcast target.

stream_key
string

Stream Key represents a stream identifier on the third party live streaming service to send the parent live stream to.

url
string

RTMP hostname including application name for the third party live streaming service. Example: rtmp://live.example.com/app.

Request path & query params
LIVE_STREAM_ID
string

The live stream ID

post
201
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets
Request
(application/json)
{
  "url": "rtmp://live.example.com/app",
  "stream_key": "abcdefgh",
  "passthrough": "Example"
}
Response
(application/json)
{
  "data": {
    "url": "rtmp://live.example.com/app",
    "stream_key": "abcdefgh",
    "status": "idle",
    "passthrough": "Example",
    "id": "le1axfGDc9ETqh6trHNTxGQ9XEhj02fOnX0200aAh24fwlmwzqKCYNJgw"
  }
}
Delete a Live Stream Simulcast Target
del

Delete the simulcast target using the simulcast target ID returned when creating the simulcast target. Simulcast Target can only be deleted when the parent live stream is in idle state.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets/${SIMULCAST_TARGET_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

SIMULCAST_TARGET_ID
string

The ID of the simulcast target.

del
204
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets/{SIMULCAST_TARGET_ID}
Retrieve a Live Stream Simulcast Target
get

Retrieves the details of the simulcast target created for the parent live stream. Supply the unique live stream ID and simulcast target ID that was returned in the response of create simulcast target request, and Mux will return the corresponding information.

curl https://api.mux.com/video/v1/live-streams/${LIVE_STREAM_ID}/simulcast-targets/${SIMULCAST_TARGET_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
LIVE_STREAM_ID
string

The live stream ID

SIMULCAST_TARGET_ID
string

The ID of the simulcast target.

get
200
/video/v1/live-streams/{LIVE_STREAM_ID}/simulcast-targets/{SIMULCAST_TARGET_ID}
Response
(application/json)
{
  "data": {
    "url": "rtmp://live.example.com/app",
    "stream_key": "abcdefgh",
    "status": "idle",
    "passthrough": "Example",
    "id": "02FU00rPq00fC9S6kygrqlxygGMdpW1lk00BkFpCfc2kGregEIr7brt7CQ"
  }
}

Spaces

Spaces allow developers to build real-time video and audio experiences into their applications via the Real-Time Video product.

Composited video of space sessions can be sent to live streams using broadcasts.

To add real-time video to an application, you'll also need to integrate one of our Real-Time Video SDKs.

Learn more in the Real-Time Video guides.

id
string

Unique identifier for the space. Max 255 characters.

created_at
string

Time the space was created, defined as a Unix timestamp (seconds since epoch).

type
string (default: server)
Possible values: "server"

Specify the network architecture of the space. In server spaces, all video travels through Mux's video infrastructure. Defaults to server if not set.

status
string
Possible values: "idle""active"

The status of the space. Spaces are idle when there are no participants connected, and active when there are participants connected.

passthrough
string

Arbitrary user-supplied metadata that will be included in the space details and related webhooks. Max: 255 characters.

broadcasts
array

An array of broadcast destinations.

broadcasts[]id
string

Unique identifier for the broadcast. Max 255 characters.

broadcasts[]passthrough
string

Arbitrary user-supplied metadata that will be included in the broadcast details and related webhooks. Max: 255 characters.

broadcasts[]live_stream_id
string

The ID of the live stream that the broadcast will be sent to.

broadcasts[]status
string
Possible values: "idle""active"

The status of the broadcast. You can start and stop broadcasts with the start and stop APIs.

broadcasts[]layout
string (default: gallery)
Possible values: "gallery""active-speaker"

The layout used when broadcasting the space. Defaults to gallery if not set.

broadcasts[]background
string

URL of an image to display as the background of the broadcast. Its dimensions should match the provided resolution.

broadcasts[]resolution
string (default: 1920x1080)
Possible values: "1920x1080""1280x720""1080x1920""720x1280""1080x1080""720x720"

The resolution of the composited video sent to the live stream. Defaults to 1920x1080 if not set.

active_session_id
string

Unique identifier for the current lifecycle of the space. Only set when the space is active and is set to a new value each time the space transitions from idle to active. This value is useful for logging and debugging issues. Max 255 characters.

Create a space
post

Create a new space. Spaces are used to build real-time video applications.

Request body params
type
string
(default: server)
Possible values: "server"

Specify the network architecture of the space. In server spaces, all video travels through Mux's video infrastructure. Defaults to server if not set.

passthrough
string

Arbitrary user-supplied metadata that will be included in the space details and related webhooks. Max: 255 characters.

An array of broadcast destinations you want to stream the space to. Note: By default only a single broadcast destination can be specified. Contact Mux support if you need more.

passthrough
string

Arbitrary user-supplied metadata that will be included in the broadcast details and related webhooks. Max: 255 characters.

live_stream_id
string

The ID of the live stream that you want to broadcast to.

layout
string
(default: gallery)
Possible values: "gallery""active-speaker"

The layout used when broadcasting the space. Defaults to gallery if not set.

background
string

URL of an image to display as the background of the broadcast. Its dimensions should match the provided resolution.

resolution
string
(default: 1920x1080)
Possible values: "1920x1080""1280x720""1080x1920""720x1280""1080x1080""720x720"

The resolution of the composited video sent to the live stream. Defaults to 1920x1080 if not set.

post
201
/video/v1/spaces
Request
(application/json)
{
  "type": "server"
}
Response
(application/json)
{
  "data": {
    "type": "server",
    "id": "uylLl3WuQ54CwqUB9UHySxnN66sqKue5",
    "created_at": "1607452572",
    "status": "idle"
  }
}
List spaces
get

List all spaces in the current enviroment.

Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/spaces
Response
(application/json)
{
  "data": [
    {
      "type": "server",
      "id": "uylLl3WuQ54CwqUB9UHySxnN66sqKue5",
      "created_at": "1607452572",
      "status": "idle"
    },
    {
      "type": "server",
      "id": "HK01Bq7FrEQmIu3QpRiZZ98HQOOZjm6B",
      "created_at": "1693452572",
      "status": "active"
    }
  ]
}
Retrieve a space
get

Retrieves the details of a space that has previously been created. Supply the unique space ID that was returned from your create space request, and Mux will return the information about the corresponding space. The same information is returned when creating a space.

Request path & query params
SPACE_ID
string

The space ID.

get
200
/video/v1/spaces/{SPACE_ID}
Response
(application/json)
{
  "data": {
    "type": "server",
    "id": "uylLl3WuQ54CwqUB9UHySxnN66sqKue5",
    "created_at": "1607452572",
    "status": "idle"
  }
}
Delete a space
del

Deletes a space. Spaces can only be deleted when idle.

Request path & query params
SPACE_ID
string

The space ID.

del
204
/video/v1/spaces/{SPACE_ID}
Create a space broadcast
post

Creates a new broadcast. Broadcasts are used to create composited versions of your space, which can be broadcast to live streams. Note: By default only a single broadcast destination can be specified. Contact Mux support if you need more.

Request body params
passthrough
string

Arbitrary user-supplied metadata that will be included in the broadcast details and related webhooks. Max: 255 characters.

live_stream_id
string

The ID of the live stream that you want to broadcast to.

layout
string
(default: gallery)
Possible values: "gallery""active-speaker"

The layout used when broadcasting the space. Defaults to gallery if not set.

background
string

URL of an image to display as the background of the broadcast. Its dimensions should match the provided resolution.

resolution
string
(default: 1920x1080)
Possible values: "1920x1080""1280x720""1080x1920""720x1280""1080x1080""720x720"

The resolution of the composited video sent to the live stream. Defaults to 1920x1080 if not set.

Request path & query params
SPACE_ID
string

The space ID.

post
201
/video/v1/spaces/{SPACE_ID}/broadcasts
Request
(application/json)
{
  "live_stream_id": "GQ9025mPqzyjOy3kKQW006qKTqmULW9vFO"
}
Response
(application/json)
{
  "data": {
    "id": "uylLl3WuQ54CwqUB9UHySxnN66sqKue5",
    "live_stream_id": "GQ9025mPqzyjOy3kKQW006qKTqmULW9vFO",
    "resolution": "1920x1080",
    "layout": "gallery",
    "status": "idle"
  }
}
Retrieve space broadcast
get

Retrieves the details of a broadcast of a specific space.

Request path & query params
SPACE_ID
string

The space ID.

BROADCAST_ID
string

The broadcast ID.

get
200
/video/v1/spaces/{SPACE_ID}/broadcasts/{BROADCAST_ID}
Response
(application/json)
{
  "data": {
    "id": "uylLl3WuQ54CwqUB9UHySxnN66sqKue5",
    "live_stream_id": "GQ9025mPqzyjOy3kKQW006qKTqmULW9vFO",
    "resolution": "1920x1080",
    "layout": "gallery",
    "status": "idle"
  }
}
Delete a space broadcast
del

Deletes a single broadcast of a specific space. Broadcasts can only be deleted when idle.

Request path & query params
SPACE_ID
string

The space ID.

BROADCAST_ID
string

The broadcast ID.

del
204
/video/v1/spaces/{SPACE_ID}/broadcasts/{BROADCAST_ID}
Start a space broadcast
post

Starts broadcasting a space to the associated destination. Broadcasts can only be started when the space is active (when there are participants connected).

Request path & query params
SPACE_ID
string

The space ID.

BROADCAST_ID
string

The broadcast ID.

post
200
/video/v1/spaces/{SPACE_ID}/broadcasts/{BROADCAST_ID}/start
Response
(application/json)
{
  "data": {}
}
Stop a space broadcast
post

Stops broadcasting a space, causing the destination live stream to become idle. This API also automatically calls complete on the destination live stream. Broadcasts are also automatically stopped when a space becomes idle.

Request path & query params
SPACE_ID
string

The space ID.

BROADCAST_ID
string

The broadcast ID.

post
200
/video/v1/spaces/{SPACE_ID}/broadcasts/{BROADCAST_ID}/stop
Response
(application/json)
{
  "data": {}
}

Playback ID

Operations related to the manipulation of playback IDs, through which users are able to stream videos and live streams from Mux.

id
string

Unique identifier for the PlaybackID

policy
string
Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

Retrieve an Asset or Live Stream ID
get

Retrieves the Identifier of the Asset or Live Stream associated with the Playback ID.

Request path & query params
PLAYBACK_ID
string

The live stream's playback ID.

get
200
/video/v1/playback-ids/{PLAYBACK_ID}
Response
(application/json)
{
  "data": {
    "id": "a1B2c3D4e5F6g7H8i9",
    "policy": "public",
    "object": {
      "type": "asset",
      "id": "123456789012345678"
    }
  }
}

URL Signing Keys

A URL signing key is used as the secret when signing any Mux URL. Mux requires a JSON Web Token as the value of the token query parameter. The token query parameter must be set for URLs that reference a playback ID with a signed playback policy.

id
string

Unique identifier for the Signing Key.

created_at
string

Time at which the object was created. Measured in seconds since the Unix epoch.

private_key
string

A Base64 encoded private key that can be used with the RS256 algorithm when creating a JWT. Note that this value is only returned once when creating a URL signing key.

Create a URL signing key
post

Creates a new signing key pair. When creating a new signing key, the API will generate a 2048-bit RSA key-pair and return the private key and a generated key-id; the public key will be stored at Mux to validate signed tokens.

curl https://api.mux.com/video/v1/signing-keys \
  -X POST \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
post
201
/video/v1/signing-keys
Response
(application/json)
{
  "data": {
    "private_key": "abcd123=",
    "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8",
    "created_at": "1610108345"
  }
}
List URL signing keys
get

Returns a list of URL signing keys.

curl https://api.mux.com/video/v1/signing-keys \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/signing-keys
Response
(application/json)
{
  "data": [
    {
      "id": "vI5KTQ78ohYriuvWKHY6COtZWXexHGLllxksOdZuya8",
      "created_at": "1610108345"
    },
    {
      "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo",
      "created_at": "1608632647"
    }
  ]
}
Retrieve a URL signing key
get

Retrieves the details of a URL signing key that has previously been created. Supply the unique signing key ID that was returned from your previous request, and Mux will return the corresponding signing key information. The private key is not returned in this response.

curl https://api.mux.com/video/v1/signing-keys/${SIGNING_KEY_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
SIGNING_KEY_ID
string

The ID of the signing key.

get
200
/video/v1/signing-keys/{SIGNING_KEY_ID}
Response
(application/json)
{
  "data": {
    "id": "jc6lJiCLMjyC202EXtRQ644sShzDv6x5tWJrbvUFpvmo",
    "created_at": "1608632647"
  }
}
Delete a URL signing key
del

Deletes an existing signing key. Use with caution, as this will invalidate any existing signatures and no URLs can be signed using the key again.

url https://api.mux.com/video/v1/signing-keys/${SIGNING_KEY_ID} \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
SIGNING_KEY_ID
string

The ID of the signing key.

del
204
/video/v1/signing-keys/{SIGNING_KEY_ID}

Direct Uploads

Direct upload allows you to push assets directly to Mux storage instead of needing to go through your own first. When you create a new direct upload, we'll give you back a signed URL for a Google Cloud Storage bucket. Their storage API is S3 compatible, so whatever tool you use to upload to either GCS or S3 should work, just remember you're probably uploading large video files and should take advantage of things like resumable or multipart uploads.

Particularly for customers that deal with a lot of user-generated content, it's common to expect quite a few abandoned uploads. To keep those abandoned uploads from cluttering up your asset lists, we don't create an asset for you until the upload is complete. Once that asset is created, you can expect all of the normal asset-related webhooks.

id
string

Unique identifier for the Direct Upload.

timeout
integer (default: 3600, minimum: 60, maximum: 604800)

Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked timed_out

status
string
Possible values: "waiting""asset_created""errored""cancelled""timed_out"
new_asset_settings
object

The settings to be used when creating a new asset. You can use any of the usual settings when creating an asset normally, with the exception to not include file url for creating the asset in input. You could optionally add overlay_setting and input urls to add Subtitles / Captions.

asset_id
string

Only set once the upload is in the asset_created state.

error
object

Only set if an error occurred during asset creation.

errortype
string

Label for the specific error

errormessage
string

Human readable error message

cors_origin
string

If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers.

url
string

The URL to upload the associated source media to.

test
boolean

Indicates if this is a test Direct Upload, in which case the Asset that gets created will be a test Asset.

Create a new direct upload URL
post

Creates a new direct upload, through which video content can be uploaded for ingest to Mux.

curl https://api.mux.com/video/v1/uploads \
  -X POST \
  -d '{ "cors_origin": "*", "new_asset_settings": { "playback_policy": ["public"] } }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
timeout
integer
(default: 3600, min: 60, max: 604800)

Max time in seconds for the signed upload URL to be valid. If a successful upload has not occurred before the timeout limit, the direct upload is marked timed_out

cors_origin
string

If the upload URL will be used in a browser, you must specify the origin in order for the signed URL to have the correct CORS headers.

An array of objects that each describe an input file to be used to create the asset. As a shortcut, input can also be a string URL for a file when only one input file is used. See input[].url for requirements.

url
string

The URL of the file that Mux should download and use.

  • For subtitles text tracks, the URL is the location of subtitle/captions file. Mux supports SubRip Text (SRT) and Web Video Text Tracks format for ingesting Subtitles and Closed Captions.
  • For Watermarking or Overlay, the URL is the location of the watermark image.
  • When creating clips from existing Mux assets, the URL is defined with mux://assets/{asset_id} template where asset_id is the Asset Identifier for creating the clip from.

An object that describes how the image file referenced in URL should be placed over the video (i.e. watermarking). Ensure that the URL is active and persists the entire lifespan of the video object.

vertical_align
string
Possible values: "top""middle""bottom"

Where the vertical positioning of the overlay/watermark should begin from. Defaults to "top"

vertical_margin
string

The distance from the vertical_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'middle', a positive value will shift the overlay towards the bottom and and a negative value will shift it towards the top.

horizontal_align
string
Possible values: "left""center""right"

Where the horizontal positioning of the overlay/watermark should begin from.

horizontal_margin
string

The distance from the horizontal_align starting point and the image's closest edge. Can be expressed as a percent ("10%") or as a pixel value ("100px"). Negative values will move the overlay offscreen. In the case of 'center', a positive value will shift the image towards the right and and a negative value will shift it towards the left.

width
string

How wide the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.

height
string

How tall the overlay should appear. Can be expressed as a percent ("10%") or as a pixel value ("100px"). If both width and height are left blank the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.

opacity
string

How opaque the overlay should appear, expressed as a percent. (Default 100%)

start_time
number

The time offset in seconds from the beginning of the video indicating the clip's starting marker. The default value is 0 when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

end_time
number

The time offset in seconds from the beginning of the video, indicating the clip's ending marker. The default value is the duration of the video when not included. This parameter is only applicable for creating clips when input.url has mux://assets/{asset_id} format.

type
string
Possible values: "video""audio""text"

This parameter is required for text type tracks.

text_type
string
Possible values: "subtitles"

Type of text track. This parameter only supports subtitles value. For more information on Subtitles / Closed Captions, see this blog post. This parameter is required for text type tracks.

language_code
string

The language code value must be a valid BCP 47 specification compliant value. For example, en for English or en-US for the US version of English. This parameter is required for text type and subtitles text type track.

name
string

The name of the track containing a human-readable description. This value must be unique across all text type and subtitles text type tracks. The hls manifest will associate a subtitle text track with this value. For example, the value should be "English" for subtitles text track with language_code as en. This optional parameter should be used only for text type and subtitles text type tracks. If this parameter is not included, Mux will auto-populate based on the input[].language_code value.

closed_captions
boolean

Indicates the track provides Subtitles for the Deaf or Hard-of-hearing (SDH). This optional parameter should be used for text type and subtitles text type tracks.

passthrough
string

This optional parameter should be used for text type and subtitles text type tracks.

playback_policy
array

An array of playback policy names that you want applied to this asset and available through playback_ids. Options include: "public" (anyone with the playback URL can stream the asset). And "signed" (an additional access token is required to play the asset). If no playback_policy is set, the asset will have no playback IDs and will therefore not be playable. For simplicity, a single string name can be used in place of the array in the case of only one playback policy.

Possible values: "public""signed"
  • public playback IDs are accessible by constructing an HLS URL like https://stream.mux.com/${PLAYBACK_ID}

  • signed playback IDs should be used with tokens https://stream.mux.com/${PLAYBACK_ID}?token={TOKEN}. See Secure video playback for details about creating tokens.

passthrough
string

Arbitrary user-supplied metadata that will be included in the asset details and related webhooks. Can be used to store your own ID for a video along with the asset. Max: 255 characters.

mp4_support
string
Possible values: "none""standard"

Specify what level (if any) of support for mp4 playback. In most cases you should use our default HLS-based streaming playback ({playback_id}.m3u8) which can automatically adjust to viewers' connection speeds, but an mp4 can be useful for some legacy devices or downloading for offline playback. See the Download your videos guide for more information.

normalize_audio
boolean
(default: false)

Normalize the audio track loudness level. This parameter is only applicable to on-demand (not live) assets.

master_access
string
Possible values: "none""temporary"

Specify what level (if any) of support for master access. Master access can be enabled temporarily for your asset to be downloaded. See the Download your videos guide for more information.

test
boolean

Marks the asset as a test asset when the value is set to true. A Test asset can help evaluate the Mux Video APIs without incurring any cost. There is no limit on number of test assets created. Test asset are watermarked with the Mux logo, limited to 10 seconds, deleted after 24 hrs.

test
boolean
post
201
/video/v1/uploads
Request
(application/json)
{
  "cors_origin": "https://example.com/",
  "new_asset_settings": {
    "playback_policy": [
      "public"
    ],
    "mp4_support": "standard"
  }
}
Response
(application/json)
{
  "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ",
  "timeout": 3600,
  "status": "waiting",
  "new_asset_settings": {
    "playback_policies": [
      "public"
    ],
    "mp4_support": "standard"
  },
  "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
  "cors_origin": "https://example.com/"
}
List direct uploads
get

Lists currently extant direct uploads in the current environment.

curl https://api.mux.com/video/v1/uploads \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/uploads
Response
(application/json)
{
  "data": [
    {
      "url": "https://storage.googleapis.com/video-storage-us-east1-uploads/zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc?Expires=1610112458&GoogleAccessId=mux-direct-upload%40mux-cloud.iam.gserviceaccount.com&Signature=LCu4PMoKUo%2BJkWQAUwB9WU4bWVVfW3K5bZxSxEptBz3DrjbFxNyGvs0sriyJupZh9Jdb6FxKWFIRbxEetfnAAiesOvSPH%2F1GlIichmGg3YfebfxiX77%2B6ToFF6FMkJucBo284PD90AVLHhKagOea2VsbdO0fh78MAxGH9sEspyQ2uJEfYWjHFqYQ9smJyIuM3CYOmN5HKPgRWy2yUqzV7OTMe%2FivPO4%2FX6XiiN2J4nTmy83252CJUsHIvbiGctfKxcNI6b23UVN4B1tJTVgyxTOZiBQCkMLkD%2FEe5OhoAkvJgkqENRr0q3swO0IChDDWjrh7OTMwqvWGwAoVXEGiHg%3D%3D&upload_id=ABg5-UznTdib1HhOAMjdHhWIYqBbwmSYM6dVKyPe3v33uTeEE8gkN5QzvR3cei6uSZOSrjPn7bdvvDH3nhsrLBq8AjWY2qE4UQ",
      "timeout": 3600,
      "status": "waiting",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
      "cors_origin": "https://example.com/"
    },
    {
      "timeout": 3600,
      "status": "asset_created",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM",
      "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00"
    },
    {
      "timeout": 10800,
      "status": "cancelled",
      "new_asset_settings": {
        "playback_policies": [
          "public"
        ],
        "mp4_support": "standard"
      },
      "id": "AZcWu0201SqVW01LMdmVxE00m3gEWUFZPItvni1sTqF800dQ"
    }
  ]
}
Retrieve a single direct upload's info
get

Fetches information about a single direct upload in the current environment.

curl https://api.mux.com/video/v1/uploads/${UPLOAD_ID} \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
UPLOAD_ID
string

ID of the Upload

get
200
/video/v1/uploads/{UPLOAD_ID}
Response
(application/json)
{
  "data": {
    "timeout": 3600,
    "status": "asset_created",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "mp4_support": "standard"
    },
    "id": "YzoCL01HHOtAVYq4Ds9zekdHJ2XqL9e8ukPWbr01KhtvM",
    "asset_id": "AnFVqAVXfb7vVL3ypSQDMnJZunnb8nkwe02O00p2gK8P00"
  }
}
Cancel a direct upload
put

Cancels a direct upload and marks it as cancelled. If a pending upload finishes after this request, no asset will be created. This request will only succeed if the upload is still in the waiting state.

curl https://api.mux.com/video/v1/uploads/${UPLOAD_ID}/cancel \
  -X PUT \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
UPLOAD_ID
string

ID of the Upload

put
200
/video/v1/uploads/{UPLOAD_ID}/cancel
Response
(application/json)
{
  "data": {
    "timeout": 3600,
    "status": "cancelled",
    "new_asset_settings": {
      "playback_policies": [
        "public"
      ],
      "mp4_support": "standard"
    },
    "id": "zd01Pe2bNpYhxbrwYABgFE01twZdtv4M00kts2i02GhbGjc",
    "cors_origin": "https://example.com/"
  }
}

Delivery Usage

The Delivery Usage API allows you to get delivery/streaming usage details for each asset and across all assets. Delivery usage details are aggregated every hour at the top of the hour and can be requested for a specified time window within the last 90 days starting at 12 hours prior to when the request is made.

Assets are ordered by delivery usage starting with the one with the highest usage. Only assets with delivery usage greater than 0 seconds are returned in the response.

live_stream_id
string

Unique identifier for the live stream that created the asset.

asset_id
string

Unique identifier for the asset.

passthrough
string

The passthrough value for the asset.

created_at
string

Time at which the asset was created. Measured in seconds since the Unix epoch.

deleted_at
string

If exists, time at which the asset was deleted. Measured in seconds since the Unix epoch.

asset_state
string
Possible values: "ready""errored""deleted"

The state of the asset.

asset_duration
number

The duration of the asset in seconds.

delivered_seconds
number

Total number of delivered seconds during this time window.

List Usage
get

Returns a list of delivery usage records and their associated Asset IDs or Live Stream IDs.

curl 'https://api.mux.com/video/v1/delivery-usage?timeframe[]=${START_TIME}&timeframe[]=${END_TIME}'   -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
page
integer
(default: 1)

Offset by this many pages, of the size of limit

limit
integer
(default: 100)

Number of items to include in the response

asset_id
string

Filter response to return delivery usage for this asset only. You cannot specify both the asset_id and live_stream_id parameters together.

live_stream_id
string

Filter response to return delivery usage for assets for this live stream. You cannot specify both the asset_id and live_stream_id parameters together.

timeframe[]
array

Time window to get delivery usage information. timeframe[0] indicates the start time, timeframe[1] indicates the end time in seconds since the Unix epoch. Default time window is 1 hour representing usage from 13th to 12th hour from when the request is made.

get
200
/video/v1/delivery-usage
Response
(application/json)
{
  "total_row_count": 2,
  "timeframe": [
    1607817600,
    1607990400
  ],
  "page": 1,
  "limit": 100,
  "data": [
    {
      "live_stream_id": "B65hEUWW01ErVKDDGImKcBquYhwEAkjW6Ic3lPY0299Cc",
      "delivered_seconds": 206.366667,
      "deleted_at": "1607945257",
      "created_at": "1607939184",
      "asset_state": "deleted",
      "asset_id": "Ww4v2q2H4MNbHIAM2wApKb3cmrh7eHjGLUjdKohR5wM",
      "asset_duration": 154.366667
    },
    {
      "delivered_seconds": 30,
      "deleted_at": "1607935288",
      "created_at": "1607617107",
      "asset_state": "deleted",
      "asset_id": "Qlb007on1TwN43XLIG027QJlUxm3jd01v5PRi1aXhnyFZY",
      "asset_duration": 98.773667
    }
  ]
}

Playback Restrictions

Playback Restrictions allows you to set additional rules for playing videos. You can set the domains/hostnames allowed to play your videos. For instance, viewers can play videos embedded on the https://example.com website when you set the Playback Restrictions with example.com as an allowed domain. Any Video requests from other websites are denied.

data
object
dataid
string

Unique identifier for the Playback Restriction. Max 255 characters.

datacreated_at
string

Time the Playback Restriction was created, defined as a Unix timestamp (seconds since epoch).

dataupdated_at
string

Time the Playback Restriction was last updated, defined as a Unix timestamp (seconds since epoch).

datareferrer
object

A list of domains allowed to play your videos.

datareferrerallowed_domains
array

List of domains allowed to play videos. Possible values are

  • [] Empty Array indicates deny video playback requests for all domains
  • ["*"] A Single Wildcard * entry means allow video playback requests from any domain
  • ["*.example.com", "foo.com"] A list of up to 10 domains or valid dns-style wildcards
datareferrerallow_no_referrer
boolean (default: false)

A boolean to determine whether to allow or deny HTTP requests without Referer HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a Referer HTTP header. Set this value to true to allow these playback requests.

Create a Playback Restriction
post

Create a new Playback Restriction.

curl 'https://api.mux.com/video/v1/playback-restrictions' \
  -X POST \
  -d '{ "referrer": { "allowed_domains": ["*.example.com"], "allow_no_referrer": true } }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params

A list of domains allowed to play your videos.

allowed_domains
array

List of domains allowed to play videos. Possible values are

  • [] Empty Array indicates deny video playback requests for all domains
  • ["*"] A Single Wildcard * entry means allow video playback requests from any domain
  • ["*.example.com", "foo.com"] A list of up to 10 domains or valid dns-style wildcards
allow_no_referrer
boolean
(default: false)

A boolean to determine whether to allow or deny HTTP requests without Referer HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a Referer HTTP header. Set this value to true to allow these playback requests.

post
201
/video/v1/playback-restrictions
Request
(application/json)
{
  "referrer": {
    "allowed_domains": [
      "*.example.com"
    ],
    "allow_no_referrer": true
  }
}
Response
(application/json)
{
  "data": {
    "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O",
    "updated_at": "1607945257",
    "created_at": "1607945257",
    "referrer": {
      "allowed_domains": [
        "*.example.com"
      ],
      "allow_no_referrer": true
    }
  }
}
List Playback Restrictions
get

Returns a list of all Playback Restrictions.

curl 'https://api.mux.com/video/v1/playback-restrictions' \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
page
integer
(default: 1)

Offset by this many pages, of the size of limit

limit
integer
(default: 25)

Number of items to include in the response

get
200
/video/v1/playback-restrictions
Response
(application/json)
{
  "total_row_count": 2,
  "page": 1,
  "limit": 100,
  "data": [
    {
      "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O",
      "updated_at": "1607945257",
      "created_at": "1607939184",
      "referrer": {
        "allowed_domains": [
          "*.example.com"
        ],
        "allow_no_referrer": false
      }
    },
    {
      "id": "012uTQqPygDYWz3jey8cyOX9n01Bd5SDH1",
      "updated_at": "1607945980",
      "created_at": "1607939188",
      "referrer": {
        "allowed_domains": [
          "a.example.com",
          "b.example.com"
        ],
        "allow_no_referrer": true
      }
    }
  ]
}
Delete a Playback Restriction
del

Deletes a single Playback Restriction.

curl 'https://api.mux.com/video/v1/playback-restrictions/${PLAYBACK_RESTRICTION_ID}' \
  -X DELETE \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
PLAYBACK_RESTRICTION_ID
string

ID of the Playback Restriction.

del
204
/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}
Retrieve a Playback Restriction
get

Retrieves a Playback Restriction associated with the unique identifier.

curl 'https://api.mux.com/video/v1/playback-restrictions/${PLAYBACK_RESTRICTION_ID}' \
  -X GET \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request path & query params
PLAYBACK_RESTRICTION_ID
string

ID of the Playback Restriction.

get
200
/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}
Response
(application/json)
{
  "data": {
    "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O",
    "updated_at": "1607945257",
    "created_at": "1607939184",
    "referrer": {
      "allowed_domains": [
        "*.example.com"
      ],
      "allow_no_referrer": false
    }
  }
}
Update the Referrer Playback Restriction
put

Allows you to modify the list of domains or change how Mux validates playback requests without the Referer HTTP header. The Referrer restriction fully replaces the old list with this new list of domains.

curl 'https://api.mux.com/video/v1/playback-restrictions/${PLAYBACK_RESTRICTION_ID}/referrer' \
  -X PUT \
  -d '{ "allowed_domains": ["*.example.com"], "allow_no_referrer": true }' \
  -H "Content-Type: application/json" \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}
Request body params
allowed_domains
array

List of domains allowed to play videos. Possible values are

  • [] Empty Array indicates deny video playback requests for all domains
  • ["*"] A Single Wildcard * entry means allow video playback requests from any domain
  • ["*.example.com", "foo.com"] A list of up to 10 domains or valid dns-style wildcards
allow_no_referrer
boolean
(default: false)

A boolean to determine whether to allow or deny HTTP requests without Referer HTTP request header. Playback requests coming from non-web/native applications like iOS, Android or smart TVs will not have a Referer HTTP header. Set this value to true to allow these playback requests.

Request path & query params
PLAYBACK_RESTRICTION_ID
string

ID of the Playback Restriction.

put
200
/video/v1/playback-restrictions/{PLAYBACK_RESTRICTION_ID}/referrer
Request
(application/json)
{
  "allowed_domains": [
    "*.example.com"
  ],
  "allow_no_referrer": true
}
Response
(application/json)
{
  "data": {
    "id": "9dbEg8o00uqQzZbzJT6NXdqNA00SdnSo8O",
    "updated_at": "1607945257",
    "created_at": "1607939184",
    "referrer": {
      "allowed_domains": [
        "*.example.com"
      ],
      "allow_no_referrer": true
    }
  }
}

Transcription Vocabularies

Transcription Vocabularies allows you to provide collections of phrases like proper nouns, technical jargon, and uncommon words as part of captioning workflows. When using Auto-Generated Captions, Transcription Vocabularies increase the likelihood of correct speech recognition for these words and phrases.

Create a Transcription Vocabulary
post

Create a new Transcription Vocabulary.

Request body params
name
string

The user-supplied name of the Transcription Vocabulary.

phrases
array

Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's generated_subtitles, the probability of successful speech recognition for these words or phrases is boosted.

passthrough
string

Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters.

post
201
/video/v1/transcription-vocabularies
Request
(application/json)
{
  "name": "Mux API Vocabulary",
  "phrases": [
    "Mux",
    "Live Stream",
    "Playback ID",
    "video encoding"
  ]
}
Response
(application/json)
{
  "data": {
    "id": "VDm3npt2eaEDvz9emzun8Q",
    "name": "Mux API Vocabulary",
    "phrases": [
      "Mux",
      "Live Stream",
      "Playback ID",
      "video encoding"
    ],
    "created_at": "1609869152",
    "updated_at": "1609869152"
  }
}
List Transcription Vocabularies
get

List all Transcription Vocabularies.

Request path & query params
limit
integer
(default: 10, max: 10)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

get
200
/video/v1/transcription-vocabularies
Response
(application/json)
{
  "data": [
    {
      "id": "VDm3npt2eaEDvz9emzun8Q",
      "name": "Mux API Vocabulary",
      "phrases": [
        "Mux",
        "Live Stream",
        "Playback ID",
        "video encoding"
      ],
      "created_at": "1609869152",
      "updated_at": "1609870000"
    },
    {
      "id": "M1lDlzSP102NgukTnyQyLqw",
      "name": "Video Codecs",
      "phrases": [
        "h.264",
        "HEVC",
        "AV1"
      ],
      "created_at": "1609869152",
      "updated_at": "1609870000"
    }
  ]
}
Retrieve a Transcription Vocabulary
get

Retrieves the details of a Transcription Vocabulary that has previously been created. Supply the unique Transcription Vocabulary ID and Mux will return the corresponding Transcription Vocabulary information. The same information is returned when creating a Transcription Vocabulary.

Request path & query params
TRANSCRIPTION_VOCABULARY_ID
string

The ID of the Transcription Vocabulary.

get
200
/video/v1/transcription-vocabularies/{TRANSCRIPTION_VOCABULARY_ID}
Response
(application/json)
{
  "data": {
    "id": "VDm3npt2eaEDvz9emzun8Q",
    "name": "Mux API Vocabulary",
    "phrases": [
      "Mux",
      "Live Stream",
      "Playback ID",
      "video encoding"
    ],
    "created_at": "1609869152",
    "updated_at": "1609870000"
  }
}
Delete a Transcription Vocabulary
del

Deletes a Transcription Vocabulary. The Transcription Vocabulary's ID will be disassociated from any live streams using it. Transcription Vocabularies can be deleted while associated live streams are active. However, the words and phrases in the deleted Transcription Vocabulary will remain attached to those streams while they are active.

Request path & query params
TRANSCRIPTION_VOCABULARY_ID
string

The ID of the Transcription Vocabulary.

del
204
/video/v1/transcription-vocabularies/{TRANSCRIPTION_VOCABULARY_ID}
Update a Transcription Vocabulary
put

Updates the details of a previously-created Transcription Vocabulary. Updates to Transcription Vocabularies are allowed while associated live streams are active. However, updates will not be applied to those streams while they are active.

Request body params
name
string

The user-supplied name of the Transcription Vocabulary.

phrases
array

Phrases, individual words, or proper names to include in the Transcription Vocabulary. When the Transcription Vocabulary is attached to a live stream's generated_subtitles, the probability of successful speech recognition for these words or phrases is boosted.

passthrough
string

Arbitrary user-supplied metadata set for the Transcription Vocabulary. Max 255 characters.

Request path & query params
TRANSCRIPTION_VOCABULARY_ID
string

The ID of the Transcription Vocabulary.

put
200
/video/v1/transcription-vocabularies/{TRANSCRIPTION_VOCABULARY_ID}
Request
(application/json)
{
  "name": "Mux API Vocabulary - Updated",
  "phrases": [
    "Mux",
    "Live Stream",
    "RTMP",
    "Stream Key"
  ]
}
Response
(application/json)
{
  "data": {
    "id": "VDm3npt2eaEDvz9emzun8Q",
    "name": "Mux API Vocabulary - Updated",
    "phrases": [
      "Mux",
      "Live Stream",
      "RTMP",
      "Stream Key"
    ],
    "created_at": "1609869152",
    "updated_at": "1609870000"
  }
}

Video Views

An individual video view tracked by Mux Data. For the full list of properties for each view please refer to the table of data fields in the Export raw video view data guide.

List Video Views
get

Returns a list of video views which match the filters and have a view_end within the specified timeframe.

Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

viewer_id
string

Viewer ID to filter results by. This value may be provided by the integration, or may be created by Mux.

error_id
integer

Filter video views by the provided error ID (as returned in the error_type_id field in the list video views endpoint). If you provide any as the error ID, this will filter the results to those with any error.

order_direction
string
Possible values: "asc""desc"

Sort order.

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/video-views
Response
(application/json)
{
  "total_row_count": 4,
  "timeframe": [
    1610025789,
    1610112189
  ],
  "data": [
    {
      "viewer_os_family": "OS X",
      "viewer_application_name": "Chrome",
      "view_start": "2021-01-07T20:34:06Z",
      "view_end": "2021-01-07T20:46:04Z",
      "video_title": "my-title",
      "total_row_count": 4,
      "player_error_message": null,
      "player_error_code": null,
      "id": "JpA81zBfGaGZ85C6aGF3bptyD4CKwpdNgamr",
      "error_type_id": 1,
      "country_code": "US"
    },
    {
      "viewer_os_family": "OS X",
      "viewer_application_name": "Chrome",
      "view_start": "2021-01-07T20:21:53Z",
      "view_end": "2021-01-07T20:34:03Z",
      "video_title": "",
      "total_row_count": 4,
      "player_error_message": null,
      "player_error_code": null,
      "id": "jPVLR5giYMrLYbHM88Tkn3cM3qCRDk0jL114",
      "error_type_id": 1,
      "country_code": "US"
    },
    {
      "viewer_os_family": "OS X",
      "viewer_application_name": "Chrome",
      "view_start": "2021-01-07T15:16:06Z",
      "view_end": "2021-01-07T15:17:06Z",
      "video_title": "Video Test Title 12.14.20",
      "total_row_count": 4,
      "player_error_message": "this is an error message from the player",
      "player_error_code": "1001",
      "id": "pdLDVKBuPZJJ9YsPVmtmB9FG9gsWBWMmYar4",
      "error_type_id": 1,
      "country_code": "US"
    },
    {
      "viewer_os_family": "OS X",
      "viewer_application_name": "Chrome",
      "view_start": "2021-01-07T15:15:09Z",
      "view_end": "2021-01-07T15:15:17Z",
      "video_title": "Video Test Title 12.14.20",
      "total_row_count": 4,
      "player_error_message": null,
      "player_error_code": null,
      "id": "zbZPowWtD3z54jcGMLCJJpF79zCjB03bV7o8",
      "error_type_id": 1,
      "country_code": "US"
    }
  ]
}
Get a Video View
get

Returns the details of a video view.

Request path & query params
VIDEO_VIEW_ID
string

ID of the Video View

get
200
/data/v1/video-views/{VIDEO_VIEW_ID}
Response
(application/json)
{
  "total_row_count": null,
  "timeframe": [
    1643133378,
    1643219778
  ],
  "data": {
    "view_end": "2022-01-26T17:56:12Z",
    "viewer_device_model": "iPhone10,4",
    "viewer_os_version": "15.1",
    "video_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy",
    "view_playing_time": "58134",
    "exit_before_video_start": false,
    "player_mux_plugin_name": "apple-mux",
    "view_max_downscale_percentage": "0.32222223",
    "country_name": "United States",
    "view_id": "8d00a0ca-8456-4e55-9ff8-dc501814a6b1",
    "view_start": "2022-01-26T17:08:18Z",
    "view_max_playhead_position": "41126",
    "player_source_host_name": "stream.mux.com",
    "player_error_code": "1001",
    "player_error_message": "error from player",
    "player_source_url": "https://stream.mux.com/ax9qwyTIaUDLdmhesYDKir5kfE4Ve215.m3u8",
    "city": "Austin",
    "view_max_upscale_percentage": "0",
    "asset_id": "rmp7fvw5lPD01l8PZ2aN74js84XrTWxHy",
    "events": [
      {
        "viewer_time": 1643216891851,
        "playback_time": 0,
        "name": "playerready",
        "event_time": 1643216898061
      },
      {
        "viewer_time": 1643216891853,
        "playback_time": 0,
        "name": "viewstart",
        "event_time": 1643216898101
      }
    ],
    "view_total_content_playback_time": 37521,
    "asn": 11427,
    "weighted_average_bitrate": 697078
  }
}

Errors

Playback errors are tracked and aggregated by Mux Data. Errors can be listed by the API, which contains data about the error code, message, and how often the error occurred.

id
integer

A unique identifier for this error.

percentage
number

The percentage of views that experienced this error.

notes
string

Notes that are attached to this error.

message
string

The error message.

last_seen
string

The last time this error was seen (ISO 8601 timestamp).

description
string

Description of the error.

count
integer

The total number of views that experiend this error.

code
integer

The error code

List Errors
get

Returns a list of errors.

Request path & query params
filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/errors
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610027061,
    1610113461
  ],
  "data": [
    {
      "percentage": 30,
      "notes": "a helpful note",
      "message": "an error message",
      "last_seen": "2021-01-08T13:42:39Z",
      "id": 1,
      "description": "a description for this error",
      "count": 1,
      "code": 100
    }
  ]
}

Filters

Deprecated, please refer to the Dimensions APIs.

List Filters
get
Deprecated

The API has been replaced by the list-dimensions API call.

Lists all the filters broken out into basic and advanced.

get
200
/data/v1/filters
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610027251,
    1610113651
  ],
  "data": {
    "basic": [
      "browser",
      "operating_system",
      "player_remote_played",
      "player_software",
      "player_software_version",
      "player_mux_plugin_name",
      "player_mux_plugin_version",
      "player_autoplay",
      "player_preload",
      "video_title",
      "video_id",
      "stream_type",
      "source_type",
      "source_hostname",
      "continent_code",
      "country",
      "player_error_code"
    ],
    "advanced": [
      "browser_version",
      "operating_system_version",
      "viewer_device_name",
      "viewer_device_model",
      "viewer_device_category",
      "viewer_device_manufacturer",
      "player_name",
      "player_version",
      "video_series",
      "video_encoding_variant",
      "experiment_name",
      "sub_property_id",
      "asn",
      "cdn",
      "viewer_connection_type",
      "view_session_id",
      "region",
      "viewer_user_id",
      "exit_before_video_start",
      "preroll_ad_asset_hostname",
      "preroll_ad_tag_hostname",
      "preroll_played",
      "preroll_requested"
    ]
  }
}
Lists values for a specific filter
get
Deprecated

The API has been replaced by the list-dimension-values API call.

Lists the values for a filter along with a total count of related views.

Request path & query params
FILTER_ID
string

ID of the Filter

limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/filters/{FILTER_ID}
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610028123,
    1610114523
  ],
  "data": [
    {
      "value": "Chrome",
      "total_count": 5
    }
  ]
}

Exports

Exports allow you to download the daily CSV files that are generated from the video views that occurred in the previous day. Please contact support for information about enabling exports for your organization.

List property video view export links
get
Deprecated

The API has been replaced by the list-exports-views API call.

Lists the available video view exports along with URLs to retrieve them.

get
200
/data/v1/exports
Response
(application/json)
{
  "total_row_count": 10,
  "timeframe": [
    1610024528,
    1610110928
  ],
  "data": [
    "https://s3.amazonaws.com/mux-data-exports/1/2021_01_01.csv.gz?...signature...",
    "https://s3.amazonaws.com/mux-data-exports/1/2021_01_02.csv.gz?...signature...",
    "https://s3.amazonaws.com/mux-data-exports/1/2021_01_03.csv.gz?...signature..."
  ]
}
List available property view exports
get

Lists the available video view exports along with URLs to retrieve them.

get
200
/data/v1/exports/views
Response
(application/json)
{
  "total_row_count": 7,
  "timeframe": [
    1626296941,
    1626383341
  ],
  "data": [
    {
      "files": [
        {
          "version": 2,
          "type": "csv",
          "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_03.csv.gz?...signature..."
        }
      ],
      "export_date": "2021-01-03"
    },
    {
      "files": [
        {
          "version": 2,
          "type": "csv",
          "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_02.csv.gz?...signature..."
        }
      ],
      "export_date": "2021-01-02"
    },
    {
      "files": [
        {
          "version": 2,
          "type": "csv",
          "path": "https://s3.amazonaws.com/mux-data-exports/1/2021_01_01.csv.gz?...signature..."
        }
      ],
      "export_date": "2021-01-01"
    }
  ]
}

Metrics

Historical metrics are used for tracking KPIs, diagnosing issues, and measuring viewers' quality of experience. Metrics are calculated using the video views that have been completed and are bucketed on the view end time for quality of experience metrics and view start time for engagement metrics. Historical metrics provide a large collection of dimensions that can be used to aggregate quality of experience based on view metadata. You can also easily compare experiences across viewer populations to, for example, find issues with specific devices or geographies.

Historical metrics are similar but not directly comparable to the real-time metrics in the Real-time APIs. These metrics are aggregated for long-term storage historical reporting and are generated using different viewer populations.

List breakdown values
get

List the breakdown values for a specific metric.

Request path & query params
METRIC_ID
string
Possible values: "aggregate_startup_time""downscale_percentage""exits_before_video_start""max_downscale_percentage""max_upscale_percentage""page_load_time""playback_failure_percentage""playback_failure_score""player_startup_time""playing_time""rebuffer_count""rebuffer_duration""rebuffer_frequency""rebuffer_percentage""rebuffer_score""requests_for_first_preroll""seek_latency""startup_time_score""unique_viewers""upscale_percentage""video_quality_score""video_startup_preroll_load_time""video_startup_preroll_request_time""video_startup_time""viewer_experience_score""views""weighted_average_bitrate"

ID of the Metric

group_by
string
Possible values: "asn""browser""browser_version""cdn""continent_code""country""exit_before_video_start""experiment_name""operating_system""operating_system_version""player_autoplay""player_error_code""player_mux_plugin_name""player_mux_plugin_version""player_name""player_preload""player_remote_played""player_software""player_software_version""player_version""preroll_ad_asset_hostname""preroll_ad_tag_hostname""preroll_played""preroll_requested""region""source_hostname""source_type""stream_type""sub_property_id""video_encoding_variant""video_id""video_series""video_title""view_session_id""viewer_connection_type""viewer_device_category""viewer_device_manufacturer""viewer_device_model""viewer_device_name""viewer_user_id"

Breakdown value to group the results by

measurement
string
Possible values: "95th""median""avg""count""sum"

Measurement for the provided metric. If omitted, the default for the metric will be used.

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

order_by
string
Possible values: "negative_impact""value""views""field"

Value to order the results by

order_direction
string
Possible values: "asc""desc"

Sort order.

timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/metrics/{METRIC_ID}/breakdown
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610028298,
    1610114698
  ],
  "meta": {
    "aggregation": "view_end"
  },
  "data": [
    {
      "views": 5,
      "value": 4,
      "total_watch_time": 513934,
      "total_playing_time": 413934,
      "negative_impact": 1,
      "field": "US"
    }
  ]
}
Get Overall values
get

Returns the overall value for a specific metric, as well as the total view count, watch time, and the Mux Global metric value for the metric.

Request path & query params
METRIC_ID
string
Possible values: "aggregate_startup_time""downscale_percentage""exits_before_video_start""max_downscale_percentage""max_upscale_percentage""page_load_time""playback_failure_percentage""playback_failure_score""player_startup_time""playing_time""rebuffer_count""rebuffer_duration""rebuffer_frequency""rebuffer_percentage""rebuffer_score""requests_for_first_preroll""seek_latency""startup_time_score""unique_viewers""upscale_percentage""video_quality_score""video_startup_preroll_load_time""video_startup_preroll_request_time""video_startup_time""viewer_experience_score""views""weighted_average_bitrate"

ID of the Metric

timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
measurement
string
Possible values: "95th""median""avg""count""sum"

Measurement for the provided metric. If omitted, the default for the metric will be used.

get
200
/data/v1/metrics/{METRIC_ID}/overall
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610029525,
    1610115925
  ],
  "meta": {
    "aggregation": "view_end"
  },
  "data": {
    "value": 4,
    "total_watch_time": 513934,
    "total_playing_time": 413934,
    "total_views": 5,
    "global_value": 1169.1832095168065
  }
}
List Insights
get

Returns a list of insights for a metric. These are the worst performing values across all breakdowns sorted by how much they negatively impact a specific metric.

Request path & query params
METRIC_ID
string
Possible values: "aggregate_startup_time""downscale_percentage""exits_before_video_start""max_downscale_percentage""max_upscale_percentage""page_load_time""playback_failure_percentage""playback_failure_score""player_startup_time""playing_time""rebuffer_count""rebuffer_duration""rebuffer_frequency""rebuffer_percentage""rebuffer_score""requests_for_first_preroll""seek_latency""startup_time_score""unique_viewers""upscale_percentage""video_quality_score""video_startup_preroll_load_time""video_startup_preroll_request_time""video_startup_time""viewer_experience_score""views""weighted_average_bitrate"

ID of the Metric

measurement
string
Possible values: "95th""median""avg""count""sum"

Measurement for the provided metric. If omitted, the default for the metric will be used.

order_direction
string
Possible values: "asc""desc"

Sort order.

timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/metrics/{METRIC_ID}/insights
Response
(application/json)
{
  "total_row_count": 18,
  "timeframe": [
    1610029610,
    1610116010
  ],
  "meta": {
    "aggregation": "view_end"
  },
  "data": [
    {
      "total_watch_time": 351144,
      "total_playing_time": 341144,
      "total_views": 1,
      "negative_impact_score": -5,
      "metric": 9,
      "filter_value": "",
      "filter_column": "video_title"
    },
    {
      "total_watch_time": 513934,
      "total_views": 5,
      "negative_impact_score": 0,
      "metric": 4,
      "filter_value": "US",
      "filter_column": "country"
    }
  ]
}
Get metric timeseries data
get

Returns timeseries data for a specific metric.

Each interval represented in the data array contains an array with the following values:

  • the first element is the interval time
  • the second element is the calculated metric value
  • the third element is the number of views in the interval that have a valid metric value
Request path & query params
METRIC_ID
string
Possible values: "aggregate_startup_time""downscale_percentage""exits_before_video_start""max_downscale_percentage""max_upscale_percentage""page_load_time""playback_failure_percentage""playback_failure_score""player_startup_time""playing_time""rebuffer_count""rebuffer_duration""rebuffer_frequency""rebuffer_percentage""rebuffer_score""requests_for_first_preroll""seek_latency""startup_time_score""unique_viewers""upscale_percentage""video_quality_score""video_startup_preroll_load_time""video_startup_preroll_request_time""video_startup_time""viewer_experience_score""views""weighted_average_bitrate"

ID of the Metric

timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
measurement
string
Possible values: "95th""median""avg""count""sum"

Measurement for the provided metric. If omitted, the default for the metric will be used.

order_direction
string
Possible values: "asc""desc"

Sort order.

group_by
string
Possible values: "ten_minutes""hour""day"

Time granularity to group results by. If this value is omitted, a default granularity is chosen based on the timeframe.

For timeframes of 6 hours or less, the default granularity is ten_minutes. Between 6 hours and 15 days inclusive, the default granularity is hour. The granularity of timeframes that exceed 15 days is day. This default behavior is subject to change; it is strongly suggested that you explicitly specify the granularity.

get
200
/data/v1/metrics/{METRIC_ID}/timeseries
Response
(application/json)
{
  "total_row_count": 2,
  "timeframe": [
    1610029711,
    1610116111
  ],
  "meta": {
    "aggregation": "view_end"
  },
  "data": [
    [
      "2021-01-07T14:00:00Z",
      "0.8743536882994202",
      "154240"
    ],
    [
      "2021-01-07T15:00:00Z",
      "0.8929105055911401",
      "156056"
    ]
  ]
}
List all metric values
get

List all of the values across every breakdown for a specific metric.

Request path & query params
timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
dimension
string
Possible values: "asn""browser""browser_version""cdn""continent_code""country""exit_before_video_start""experiment_name""operating_system""operating_system_version""player_autoplay""player_error_code""player_mux_plugin_name""player_mux_plugin_version""player_name""player_preload""player_remote_played""player_software""player_software_version""player_version""preroll_ad_asset_hostname""preroll_ad_tag_hostname""preroll_played""preroll_requested""region""source_hostname""source_type""stream_type""sub_property_id""video_encoding_variant""video_id""video_series""video_title""view_session_id""viewer_connection_type""viewer_device_category""viewer_device_manufacturer""viewer_device_model""viewer_device_name""viewer_user_id"

Dimension the specified value belongs to

value
string

Value to show all available metrics for

get
200
/data/v1/metrics/comparison
Response
(application/json)
{
  "total_row_count": 1,
  "timeframe": [
    1610029906,
    1610116306
  ],
  "data": [
    {
      "watch_time": 513934,
      "view_count": 5,
      "started_views": 6,
      "ended_views": 5,
      "unique_viewers": 6,
      "total_playing_time": 503934,
      "name": "totals"
    },
    {
      "value": 6,
      "type": "number",
      "name": "Views",
      "metric": "views",
      "items": [
        {
          "value": 6,
          "type": "number",
          "name": "Unique Viewers",
          "metric": "unique_viewers"
        },
        {
          "value": 503934,
          "type": "milliseconds",
          "name": "Playing Time",
          "metric": "playing_time"
        }
      ]
    },
    {
      "value": 0.7803472280502319,
      "type": "score",
      "name": "Overall Score",
      "metric": "viewer_experience_score"
    },
    {
      "value": 0.8,
      "type": "score",
      "name": "Playback Failure Score",
      "metric": "playback_failure_score",
      "items": [
        {
          "value": 0.2,
          "type": "percentage",
          "name": "Playback Failure Percentage",
          "metric": "playback_failure_percentage"
        }
      ]
    },
    {
      "value": 0.9991008877754212,
      "type": "score",
      "name": "Startup Time Score",
      "metric": "startup_time_score",
      "items": [
        {
          "value": 4,
          "type": "milliseconds",
          "name": "Video Startup Time (median)",
          "metric": "video_startup_time",
          "measurement": "median"
        },
        {
          "value": 9,
          "type": "milliseconds",
          "name": "Video Startup Time (95th %)",
          "metric": "video_startup_time",
          "measurement": "95th"
        },
        {
          "value": 52.5625,
          "type": "milliseconds",
          "name": "Player Startup Time (median)",
          "metric": "player_startup_time",
          "measurement": "median"
        },
        {
          "value": 60.0625,
          "type": "milliseconds",
          "name": "Player Startup Time (95th %)",
          "metric": "player_startup_time",
          "measurement": "95th"
        },
        {
          "value": 122.37890625,
          "type": "milliseconds",
          "name": "Page Load Time (median)",
          "metric": "page_load_time",
          "measurement": "median"
        },
        {
          "value": 264.0625,
          "type": "milliseconds",
          "name": "Page Load Time (95th %)",
          "metric": "page_load_time",
          "measurement": "95th"
        },
        {
          "value": 182.25,
          "type": "milliseconds",
          "name": "Aggregate Startup Time (median)",
          "metric": "aggregate_startup_time",
          "measurement": "median"
        },
        {
          "value": 319.515625,
          "type": "milliseconds",
          "name": "Aggregate Startup Time (95th %)",
          "metric": "aggregate_startup_time",
          "measurement": "95th"
        },
        {
          "value": 3042,
          "type": "milliseconds",
          "name": "Seek Latency",
          "metric": "seek_latency"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Exits Before Video Start",
          "metric": "exits_before_video_start"
        }
      ]
    },
    {
      "value": 0.9523247838020324,
      "type": "score",
      "name": "Rebuffer Score",
      "metric": "rebuffer_score",
      "items": [
        {
          "value": 0.0005564916895943838,
          "type": "percentage",
          "name": "Rebuffer Percentage",
          "metric": "rebuffer_percentage"
        },
        {
          "value": 0.11674650830651406,
          "type": "per_minute",
          "name": "Rebuffer Frequency",
          "metric": "rebuffer_frequency"
        },
        {
          "value": 0,
          "type": "milliseconds",
          "name": "Rebuffer Duration (median)",
          "metric": "rebuffer_duration",
          "measurement": "median"
        },
        {
          "value": 256,
          "type": "milliseconds",
          "name": "Rebuffer Duration (95th %)",
          "metric": "rebuffer_duration",
          "measurement": "95th"
        },
        {
          "value": 0,
          "type": "number",
          "name": "Rebuffer Count (median)",
          "metric": "rebuffer_count",
          "measurement": "median"
        },
        {
          "value": 1,
          "type": "number",
          "name": "Rebuffer Count (95th %)",
          "metric": "rebuffer_count",
          "measurement": "95th"
        }
      ]
    },
    {
      "value": 1,
      "type": "score",
      "name": "Video Quality Score",
      "metric": "video_quality_score",
      "items": [
        {
          "value": 0,
          "type": "percentage",
          "name": "Upscale Percentage (median)",
          "metric": "upscale_percentage",
          "measurement": "median"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Upscale Percentage (95th %)",
          "metric": "upscale_percentage",
          "measurement": "95th"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Upscale Percentage (average)",
          "metric": "upscale_percentage",
          "measurement": "avg"
        },
        {
          "value": 0.007,
          "type": "percentage",
          "name": "Downscale Percentage (median)",
          "metric": "downscale_percentage",
          "measurement": "median"
        },
        {
          "value": 0.449,
          "type": "percentage",
          "name": "Downscale Percentage (95th %)",
          "metric": "downscale_percentage",
          "measurement": "95th"
        },
        {
          "value": 0.11813909473676262,
          "type": "percentage",
          "name": "Downscale Percentage (average)",
          "metric": "downscale_percentage",
          "measurement": "avg"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Max Upscale Percentage (median)",
          "metric": "max_upscale_percentage",
          "measurement": "median"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Max Upscale Percentage (95th %)",
          "metric": "max_upscale_percentage",
          "measurement": "95th"
        },
        {
          "value": 0.007,
          "type": "percentage",
          "name": "Max Downscale Percentage (median)",
          "metric": "max_downscale_percentage",
          "measurement": "median"
        },
        {
          "value": 0.449,
          "type": "percentage",
          "name": "Max Downscale Percentage (95th %)",
          "metric": "max_downscale_percentage",
          "measurement": "95th"
        },
        {
          "value": 851582.91015625,
          "type": "mbps",
          "name": "Weighted Average Bitrate (median)",
          "metric": "weighted_average_bitrate",
          "measurement": "median"
        },
        {
          "value": 697016.265625,
          "type": "mbps",
          "name": "Weighted Average Bitrate (95th %)",
          "metric": "weighted_average_bitrate",
          "measurement": "95th"
        }
      ]
    }
  ]
}

Monitoring

Monitoring metrics are used for operational monitoring of a video platform. The metrics are aggregated in five second intervals, across the views that are currently being watched. The real-time metrics' timeline, breakdown, and histogram representations are available via the APIs.

Monitoring metrics are similar but not directly comparable to the historical metrics in the Metrics APIs. These metrics are aggregated to provide the most operational detail possible used for resolving operational issues.

List Monitoring Dimensions
get

Lists available monitoring dimensions.

get
200
/data/v1/monitoring/dimensions
Response
(application/json)
{
  "data": [
    {
      "display_name": "ASN",
      "name": "asn"
    },
    {
      "display_name": "CDN",
      "name": "cdn"
    },
    {
      "display_name": "Country",
      "name": "country"
    },
    {
      "display_name": "Operating system",
      "name": "operating_system"
    },
    {
      "display_name": "Player name",
      "name": "player_name"
    },
    {
      "display_name": "Region / State",
      "name": "region"
    },
    {
      "display_name": "Stream type",
      "name": "stream_type"
    },
    {
      "display_name": "Sub property ID",
      "name": "sub_property_id"
    },
    {
      "display_name": "Video series",
      "name": "video_series"
    },
    {
      "display_name": "Video title",
      "name": "video_title"
    }
  ],
  "timeframe": [
    1610034823,
    1610121223
  ],
  "total_row_count": 1
}
List Monitoring Metrics
get

Lists available monitoring metrics.

get
200
/data/v1/monitoring/metrics
Response
(application/json)
{
  "data": [
    {
      "display_name": "Current Average Bitrate",
      "name": "current-average-bitrate"
    },
    {
      "display_name": "Current Concurrent Viewers (CCV)",
      "name": "current-concurrent-viewers"
    },
    {
      "display_name": "Current Rebuffering Percentage",
      "name": "current-rebuffering-percentage"
    },
    {
      "display_name": "Exits Before Video Start",
      "name": "exits-before-video-start"
    },
    {
      "display_name": "Playback Failure Percentage",
      "name": "playback-failure-percentage"
    },
    {
      "display_name": "Video Startup Time",
      "name": "video-startup-time"
    }
  ],
  "timeframe": [
    1610034858,
    1610121258
  ],
  "total_row_count": 1
}
Get Monitoring Breakdown
get

Gets breakdown information for a specific dimension and metric along with the number of concurrent viewers and negative impact score.

Request path & query params
MONITORING_METRIC_ID
string
Possible values: "current-concurrent-viewers""current-rebuffering-percentage""exits-before-video-start""playback-failure-percentage""current-average-bitrate"

ID of the Monitoring Metric

dimension
string
Possible values: "asn""cdn""country""operating_system""player_name""region""stream_type""sub_property_id""video_series""video_title"

Dimension the specified value belongs to

timestamp
integer

Timestamp to limit results by. This value must be provided as a unix timestamp. Defaults to the current unix timestamp.

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
order_by
string
Possible values: "negative_impact""value""views""field"

Value to order the results by

order_direction
string
Possible values: "asc""desc"

Sort order.

get
200
/data/v1/monitoring/metrics/{MONITORING_METRIC_ID}/breakdown
Response
(application/json)
{
  "data": [
    {
      "concurrent_viewers": 2680,
      "metric_value": 0.008195679660675846,
      "negative_impact": 1,
      "value": "FR"
    },
    {
      "concurrent_viewers": 36,
      "metric_value": 0.010317417106767573,
      "negative_impact": 4,
      "value": "ES"
    },
    {
      "concurrent_viewers": 30,
      "metric_value": 0.06408818534303201,
      "negative_impact": 2,
      "value": "RE"
    },
    {
      "concurrent_viewers": 26,
      "metric_value": 0.008232510579858339,
      "negative_impact": 7,
      "value": "GB"
    },
    {
      "concurrent_viewers": 10,
      "metric_value": 0,
      "negative_impact": 26,
      "value": "BE"
    }
  ],
  "timeframe": [
    1610121421,
    1610121421
  ],
  "total_row_count": 1
}
Get Monitoring Histogram Timeseries
get

Gets histogram timeseries information for a specific metric.

Request path & query params
MONITORING_HISTOGRAM_METRIC_ID
string
Possible values: "video-startup-time"

ID of the Monitoring Histogram Metric

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
get
200
/data/v1/monitoring/metrics/{MONITORING_HISTOGRAM_METRIC_ID}/histogram-timeseries
Response
(application/json)
{
  "data": [
    {
      "average": 5298.1612903225805,
      "bucket_values": [
        {
          "count": 3,
          "percentage": 0.0967741935483871
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 1,
          "percentage": 0.03225806451612903
        },
        {
          "count": 16,
          "percentage": 0.5161290322580645
        },
        {
          "count": 7,
          "percentage": 0.22580645161290322
        },
        {
          "count": 4,
          "percentage": 0.12903225806451613
        }
      ],
      "max_percentage": 0.5161290322580645,
      "median": 4463,
      "p95": 14834,
      "sum": 31,
      "timestamp": "2021-01-08T15:30:00Z"
    },
    {
      "average": 3828.4146341463415,
      "bucket_values": [
        {
          "count": 5,
          "percentage": 0.12195121951219512
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 4,
          "percentage": 0.0975609756097561
        },
        {
          "count": 18,
          "percentage": 0.43902439024390244
        },
        {
          "count": 12,
          "percentage": 0.2926829268292683
        },
        {
          "count": 2,
          "percentage": 0.04878048780487805
        }
      ],
      "max_percentage": 0.43902439024390244,
      "median": 2625,
      "p95": 7378,
      "sum": 41,
      "timestamp": "2021-01-08T15:31:00Z"
    }
  ],
  "meta": {
    "bucket_unit": "milliseconds",
    "buckets": [
      {
        "end": 100,
        "start": 0
      },
      {
        "end": 500,
        "start": 100
      },
      {
        "end": 1000,
        "start": 500
      },
      {
        "end": 2000,
        "start": 1000
      },
      {
        "end": 5000,
        "start": 2000
      },
      {
        "end": 10000,
        "start": 5000
      },
      {
        "end": 15000,
        "start": 10000
      }
    ]
  },
  "timeframe": [
    1610119800,
    1610121540
  ],
  "total_row_count": 1
}
Get Monitoring Timeseries
get

Gets Time series information for a specific metric along with the number of concurrent viewers.

Request path & query params
MONITORING_METRIC_ID
string
Possible values: "current-concurrent-viewers""current-rebuffering-percentage""exits-before-video-start""playback-failure-percentage""current-average-bitrate"

ID of the Monitoring Metric

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
get
200
/data/v1/monitoring/metrics/{MONITORING_METRIC_ID}/timeseries
Response
(application/json)
{
  "data": [
    {
      "concurrent_viewers": 2790,
      "date": "2021-01-08T15:31:20Z",
      "value": 2790
    },
    {
      "concurrent_viewers": 2788,
      "date": "2021-01-08T15:31:25Z",
      "value": 2788
    },
    {
      "concurrent_viewers": 2791,
      "date": "2021-01-08T15:31:30Z",
      "value": 2791
    },
    {
      "concurrent_viewers": 2791,
      "date": "2021-01-08T15:31:35Z",
      "value": 2791
    },
    {
      "concurrent_viewers": 2792,
      "date": "2021-01-08T15:31:40Z",
      "value": 2792
    }
  ],
  "timeframe": [
    1610119880,
    1610121675
  ],
  "total_row_count": 1
}

Real-Time

The Mux Data Real-time API has been deprecated, please refer to the Mux Data Monitoring APIs which provide the same functionality.

List Real-Time Dimensions
get
Deprecated

Lists available real-time dimensions. This API is now deprecated, please use the List Monitoring Dimensions API.

get
200
/data/v1/realtime/dimensions
Response
(application/json)
{
  "data": [
    {
      "display_name": "ASN",
      "name": "asn"
    },
    {
      "display_name": "CDN",
      "name": "cdn"
    },
    {
      "display_name": "Country",
      "name": "country"
    },
    {
      "display_name": "Operating system",
      "name": "operating_system"
    },
    {
      "display_name": "Player name",
      "name": "player_name"
    },
    {
      "display_name": "Region / State",
      "name": "region"
    },
    {
      "display_name": "Stream type",
      "name": "stream_type"
    },
    {
      "display_name": "Sub property ID",
      "name": "sub_property_id"
    },
    {
      "display_name": "Video series",
      "name": "video_series"
    },
    {
      "display_name": "Video title",
      "name": "video_title"
    }
  ],
  "timeframe": [
    1610034823,
    1610121223
  ],
  "total_row_count": 1
}
List Real-Time Metrics
get
Deprecated

Lists available real-time metrics. This API is now deprecated, please use the List Monitoring Metrics API.

get
200
/data/v1/realtime/metrics
Response
(application/json)
{
  "data": [
    {
      "display_name": "Current Average Bitrate",
      "name": "current-average-bitrate"
    },
    {
      "display_name": "Current Concurrent Viewers (CCV)",
      "name": "current-concurrent-viewers"
    },
    {
      "display_name": "Current Rebuffering Percentage",
      "name": "current-rebuffering-percentage"
    },
    {
      "display_name": "Exits Before Video Start",
      "name": "exits-before-video-start"
    },
    {
      "display_name": "Playback Failure Percentage",
      "name": "playback-failure-percentage"
    },
    {
      "display_name": "Video Startup Time",
      "name": "video-startup-time"
    }
  ],
  "timeframe": [
    1610034858,
    1610121258
  ],
  "total_row_count": 1
}
Get Real-Time Breakdown
get
Deprecated

Gets breakdown information for a specific dimension and metric along with the number of concurrent viewers and negative impact score. This API is now deprecated, please use the Get Monitoring Breakdown API.

Request path & query params
REALTIME_METRIC_ID
string
Possible values: "current-concurrent-viewers""current-rebuffering-percentage""exits-before-video-start""playback-failure-percentage""current-average-bitrate"

ID of the Realtime Metric

dimension
string
Possible values: "asn""cdn""country""operating_system""player_name""region""stream_type""sub_property_id""video_series""video_title"

Dimension the specified value belongs to

timestamp
integer

Timestamp to limit results by. This value must be provided as a unix timestamp. Defaults to the current unix timestamp.

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
order_by
string
Possible values: "negative_impact""value""views""field"

Value to order the results by

order_direction
string
Possible values: "asc""desc"

Sort order.

get
200
/data/v1/realtime/metrics/{REALTIME_METRIC_ID}/breakdown
Response
(application/json)
{
  "data": [
    {
      "concurrent_viewers": 2680,
      "metric_value": 0.008195679660675846,
      "negative_impact": 1,
      "value": "FR"
    },
    {
      "concurrent_viewers": 36,
      "metric_value": 0.010317417106767573,
      "negative_impact": 4,
      "value": "ES"
    },
    {
      "concurrent_viewers": 30,
      "metric_value": 0.06408818534303201,
      "negative_impact": 2,
      "value": "RE"
    },
    {
      "concurrent_viewers": 26,
      "metric_value": 0.008232510579858339,
      "negative_impact": 7,
      "value": "GB"
    },
    {
      "concurrent_viewers": 10,
      "metric_value": 0,
      "negative_impact": 26,
      "value": "BE"
    }
  ],
  "timeframe": [
    1610121421,
    1610121421
  ],
  "total_row_count": 1
}
Get Real-Time Histogram Timeseries
get
Deprecated

Gets histogram timeseries information for a specific metric. This API is now deprecated, please use the Get Monitoring Histogram Timeseries API.

Request path & query params
REALTIME_HISTOGRAM_METRIC_ID
string
Possible values: "video-startup-time"

ID of the Realtime Histogram Metric

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
get
200
/data/v1/realtime/metrics/{REALTIME_HISTOGRAM_METRIC_ID}/histogram-timeseries
Response
(application/json)
{
  "data": [
    {
      "average": 5298.1612903225805,
      "bucket_values": [
        {
          "count": 3,
          "percentage": 0.0967741935483871
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 1,
          "percentage": 0.03225806451612903
        },
        {
          "count": 16,
          "percentage": 0.5161290322580645
        },
        {
          "count": 7,
          "percentage": 0.22580645161290322
        },
        {
          "count": 4,
          "percentage": 0.12903225806451613
        }
      ],
      "max_percentage": 0.5161290322580645,
      "median": 4463,
      "p95": 14834,
      "sum": 31,
      "timestamp": "2021-01-08T15:30:00Z"
    },
    {
      "average": 3828.4146341463415,
      "bucket_values": [
        {
          "count": 5,
          "percentage": 0.12195121951219512
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 0,
          "percentage": 0
        },
        {
          "count": 4,
          "percentage": 0.0975609756097561
        },
        {
          "count": 18,
          "percentage": 0.43902439024390244
        },
        {
          "count": 12,
          "percentage": 0.2926829268292683
        },
        {
          "count": 2,
          "percentage": 0.04878048780487805
        }
      ],
      "max_percentage": 0.43902439024390244,
      "median": 2625,
      "p95": 7378,
      "sum": 41,
      "timestamp": "2021-01-08T15:31:00Z"
    }
  ],
  "meta": {
    "bucket_unit": "milliseconds",
    "buckets": [
      {
        "end": 100,
        "start": 0
      },
      {
        "end": 500,
        "start": 100
      },
      {
        "end": 1000,
        "start": 500
      },
      {
        "end": 2000,
        "start": 1000
      },
      {
        "end": 5000,
        "start": 2000
      },
      {
        "end": 10000,
        "start": 5000
      },
      {
        "end": 15000,
        "start": 10000
      }
    ]
  },
  "timeframe": [
    1610119800,
    1610121540
  ],
  "total_row_count": 1
}
Get Real-Time Timeseries
get
Deprecated

Gets Time series information for a specific metric along with the number of concurrent viewers. This API is now deprecated, please use the Get Monitoring Timeseries API.

Request path & query params
REALTIME_METRIC_ID
string
Possible values: "current-concurrent-viewers""current-rebuffering-percentage""exits-before-video-start""playback-failure-percentage""current-average-bitrate"

ID of the Realtime Metric

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
get
200
/data/v1/realtime/metrics/{REALTIME_METRIC_ID}/timeseries
Response
(application/json)
{
  "data": [
    {
      "concurrent_viewers": 2790,
      "date": "2021-01-08T15:31:20Z",
      "value": 2790
    },
    {
      "concurrent_viewers": 2788,
      "date": "2021-01-08T15:31:25Z",
      "value": 2788
    },
    {
      "concurrent_viewers": 2791,
      "date": "2021-01-08T15:31:30Z",
      "value": 2791
    },
    {
      "concurrent_viewers": 2791,
      "date": "2021-01-08T15:31:35Z",
      "value": 2791
    },
    {
      "concurrent_viewers": 2792,
      "date": "2021-01-08T15:31:40Z",
      "value": 2792
    }
  ],
  "timeframe": [
    1610119880,
    1610121675
  ],
  "total_row_count": 1
}

Dimensions

Dimensions are the types of metadata that can be collected for a video view. Some dimensions are collected automatically based on the playback or device, such as the viewer's Country or the device information. Other dimensions are specified by the developer when configuring a Mux Data video view such as the video title. The Dimensions APIs allow you to get a list of the supported dimensions and their values.

List Dimensions
get

List all available dimensions.

Note: This API replaces the list-filters API call.

get
200
/data/v1/dimensions
Response
(application/json)
{
  "data": {
    "advanced": [
      "browser_version",
      "operating_system_version",
      "viewer_device_name",
      "viewer_device_model",
      "viewer_device_category",
      "viewer_device_manufacturer",
      "player_name",
      "player_version",
      "video_series",
      "video_encoding_variant",
      "experiment_name",
      "sub_property_id",
      "asn",
      "cdn",
      "viewer_connection_type",
      "view_session_id",
      "region",
      "viewer_user_id",
      "exit_before_video_start",
      "preroll_ad_asset_hostname",
      "preroll_ad_tag_hostname",
      "preroll_played",
      "preroll_requested"
    ],
    "basic": [
      "browser",
      "operating_system",
      "player_remote_played",
      "player_software",
      "player_software_version",
      "player_mux_plugin_name",
      "player_mux_plugin_version",
      "player_autoplay",
      "player_preload",
      "video_title",
      "video_id",
      "stream_type",
      "source_type",
      "source_hostname",
      "continent_code",
      "country",
      "player_error_code"
    ]
  },
  "timeframe": [
    1610033879,
    1610120279
  ],
  "total_row_count": 1
}
Lists the values for a specific dimension
get

Lists the values for a dimension along with a total count of related views.

Note: This API replaces the list-filter-values API call.

Request path & query params
DIMENSION_ID
string

ID of the Dimension

limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

filters[]
array

Limit the results to rows that match conditions from provided key:value pairs. Must be provided as an array query string parameter.

To exclude rows that match a certain condition, prepend a ! character to the dimension.

Possible filter names are the same as returned by the List Filters endpoint.

Example:

  • filters[]=operating_system:windows&filters[]=!country:US
timeframe[]
array

Timeframe window to limit results by. Must be provided as an array query string parameter (e.g. timeframe[]=).

Accepted formats are...

  • array of epoch timestamps e.g. timeframe[]=1498867200&timeframe[]=1498953600
  • duration string e.g. timeframe[]=24:hours or timeframe[]=7:days
get
200
/data/v1/dimensions/{DIMENSION_ID}
Response
(application/json)
{
  "data": [
    {
      "total_count": 10000,
      "value": "FR"
    },
    {
      "total_count": 5000,
      "value": "ES"
    },
    {
      "total_count": 2000,
      "value": "PT"
    },
    {
      "total_count": 100,
      "value": "DE"
    },
    {
      "total_count": 1,
      "value": "BE"
    }
  ],
  "timeframe": [
    1610033976,
    1610120376
  ],
  "total_row_count": 5
}

Incidents

Incidents occur when an anomaly alert is triggered in Mux Data. The Incidents API provides operations related to the raising and managing of alerting incidents.

List Incidents
get

Returns a list of incidents.

Request path & query params
limit
integer
(default: 25)

Number of items to include in the response

page
integer
(default: 1)

Offset by this many pages, of the size of limit

order_by
string
Possible values: "negative_impact""value""views""field"

Value to order the results by

order_direction
string
Possible values: "asc""desc"

Sort order.

status
string
Possible values: "open""closed""expired"

Status to filter incidents by

severity
string
Possible values: "warning""alert"

Severity to filter incidents by

get
200
/data/v1/incidents
Response
(application/json)
{
  "data": [
    {
      "affected_views": 71,
      "affected_views_per_hour": 29,
      "affected_views_per_hour_on_open": 75,
      "breakdowns": [
        {
          "id": "abcdef",
          "name": "error_type_id",
          "value": "697070"
        }
      ],
      "description": "Something is broken",
      "error_description": "No seriously, something is really really broken :(",
      "id": "4u13td",
      "impact": "*71 views* were affected at a rate of *29 per hour*",
      "incident_key": "5312a7c0bbb5d8353bd88602f01fe58eb15e9febac8fd2f0d8ce8f1cb138145c",
      "measured_value": 5.9,
      "measured_value_on_close": 0.1,
      "measurement": "error_rate",
      "notification_rules": [],
      "notifications": [
        {
          "attempted_at": "2021-01-05T09:52:15.119040Z",
          "id": 103014,
          "queued_at": "2021-01-05T09:52:14.945157Z"
        },
        {
          "attempted_at": "2021-01-05T11:31:08.244462Z",
          "id": 102025,
          "queued_at": "2021-01-05T11:31:08.061924Z"
        }
      ],
      "resolved_at": "2021-01-05T11:31:04.000000Z",
      "sample_size": 1000,
      "sample_size_unit": "views",
      "severity": "alert",
      "started_at": "2021-01-05T09:04:46.000000Z",
      "status": "closed",
      "threshold": 5
    },
    {
      "affected_views": 132,
      "affected_views_per_hour": 11,
      "affected_views_per_hour_on_open": 65,
      "breakdowns": [
        {
          "id": "abcdef",
          "name": "video_title",
          "value": "Layla the dog video 1337"
        },
        {
          "id": "abcdef",
          "name": "error_type_id",
          "value": "697065"
        }
      ],
      "description": "Something else is broken",
      "error_description": "Detailed error: On no!",
      "id": "rd9579",
      "impact": "*132 views* were affected at a rate of *11 per hour*",
      "incident_key": "fd9add7a85a013d768f4039f9e726133eddb476c2f16b22ebfe56f18f7c03b27",
      "measured_value": 97,
      "measured_value_on_close": 1,
      "measurement": "error_rate",
      "notification_rules": [],
      "notifications": [
        {
          "attempted_at": "2020-12-31T09:26:19.416919Z",
          "id": 102198,
          "queued_at": "2020-12-31T09:26:18.987717Z"
        },
        {
          "attempted_at": "2020-12-31T20:23:57.279325Z",
          "id": 101269,
          "queued_at": "2020-12-31T20:23:56.997068Z"
        }
      ],
      "resolved_at": "2020-12-31T20:22:54.000000Z",
      "sample_size": 100,
      "sample_size_unit": "views",
      "severity": "alert",
      "started_at": "2020-12-31T07:56:22.000000Z",
      "status": "closed",
      "threshold": 96
    }
  ],
  "timeframe": [
    1610035979,
    1610122379
  ],
  "total_row_count": 2
}
Get an Incident
get

Returns the details of an incident.

Request path & query params
INCIDENT_ID
string

ID of the Incident

get
200
/data/v1/incidents/{INCIDENT_ID}
Response
(application/json)
{
  "data": {
    "affected_views": 2026,
    "affected_views_per_hour": 84,
    "affected_views_per_hour_on_open": 12857,
    "breakdowns": [
      {
        "id": "abcdef",
        "name": "error_type_id",
        "value": "499680"
      },
      {
        "id": "abcdef",
        "name": "video_title",
        "value": "Cute dogs"
      }
    ],
    "description": "This video is erroring a lot",
    "error_description": "Error Type ID 499680",
    "id": "g7q2df",
    "impact": "*2026 views* were affected at a rate of *84 per hour*",
    "incident_key": "045dfcbefdb68c6003aaf3bf5ed217493772519f28f14d129f95eaff159ea6d6b",
    "measured_value": 100,
    "measured_value_on_close": 8,
    "measurement": "error_rate",
    "notification_rules": [],
    "notifications": [
      {
        "attempted_at": "2020-05-14T17:23:08.034662Z",
        "id": 63293,
        "queued_at": "2020-05-14T17:23:07.944457Z"
      },
      {
        "attempted_at": "2020-05-13T17:22:30.444389Z",
        "id": 62212,
        "queued_at": "2020-05-13T17:22:30.354828Z"
      }
    ],
    "resolved_at": "2020-05-14T17:22:30.000000Z",
    "sample_size": 100,
    "sample_size_unit": "views",
    "severity": "alert",
    "started_at": "2020-05-13T17:21:54.000000Z",
    "status": "closed",
    "threshold": 100
  },
  "timeframe": [
    1610036456,
    1610122856
  ],
  "total_row_count": null
}