Mux Data API

The Mux Data API is organized around RESTful concepts. We strive for resources across the API to be predictable. Concepts such as status codes, names, and data structures should feel familiar and easy to recognize.

As you work with the API, there are a few common things in the data structures. Responses will always have any data returned under the data object. Keys outside of the data object can include useful information such as warnings, timeframe and pagination details. Certain responses will not have any data returned, such as certain DELETE, POST, or other requests.

Successful request will return either 200, or in some cases, a 201 for when you create new objects.

The error codes you can expect to see include: 400, 401, 404. For most errors, there will also be information about the error under the errors object in the response. This can include a messages key with detailed information.

Feedback

We want to provide the best developer experience we possibly can when using our APIs. If you run into any problems using it, please let us know so we can update documentation, fix bugs, or whatever else needs to be done to improve the experience. Thank you for your help!

Authentication

Every request to the API is authenticated via an Access Token, which includes the ID and the secret key. You can think of the Access Token’s id as its username and secret as the password, which is important to note because Mux only stores a hash of the secret, not the secret itself. The benefit of this is that someone gaining access to our Access Token database doesn’t get any usable credentials, but this means that Mux isn’t able to recover a lost secret key if you lose it. If you do happen to lose the secret key, however, no problem! You can create (and revoke) as many as you’d like: https://dashboard.mux.com/settings/access-tokens.

API requests are authenticated via HTTP Basic Auth, where the username is the Access Token ID, and the password is the Access Token secret key. Due to the use of Basic Authentication and because doing so is just a Really Good Idea™, all API requests must made via HTTPS (to https://api.mux.com).

Authorization

Access Tokens are given certain permissions when they are created. These permissions include which Environment (the model formerly known as “Property”) the token has access to, as well as the permissions within that Environment. The possible permissions include, but are not limited to: Data (a.k.a Analytics), read access to Video, and/or write access to Video.

If your account does not have access to Mux Video, there will be no choice about permissions; all Access Tokens created for Data-only accounts will automatically only have access to the Mux Data API.

In the case that you attempt a request for which the Access Token does not have permission, you will receive a 401 respose from the API.

Getting Started

To do anything useful with the API, your API request needs to be authenticated. Select the permissions you want the Access Token to be able to access, and give it a name.

Let’s store the credentials inside some environment variables for future use:

$ export MUX_ACCESS_TOKEN_ID=<your-access-token-id> \
  MUX_ACCESS_TOKEN_SECRET=<your-access-token-secret>

To parse the JSON output of the API, we’re going to use jq, so if you don’t have that, go ahead and install it. Now, for example, we could find the filter value that’s causing the most damage to our viewer experience score.

$ curl -X GET \
  https://api.mux.com/data/v1/metrics/viewer_experience_score/insights \
  -u $MUX_ACCESS_TOKEN_ID:$MUX_ACCESS_TOKEN_SECRET \
  | jq '"Looks like (.data[0].filter_value) ((.data[0].filter_column)) is hurting viewer experience score the most"'
> "Looks like Jan Quadrant Vincent 16 (video_title) is hurting viewer experience score the most"

Great! Now we have an idea of at least one thing we could work on to improve our overall viewer experience score. 👌

Terminology

As you read through the API parameters, you’ll almost certainly see a few words used a new context.

  • Dimension: An attribute of a video view. For example the dimension “Video Title” indicates the title of the video, e.g. “Big Buck Bunny”

  • Metric: A performance metric for an environment. These metrics contribute in different ways to their corresponding Component Scores, and ultimately an environment’s overall Viewer Experience Score.

  • Breakdown: A quantitative measurement, broken out by values of a dimension. For example playback failure percentage split by operating system, or video startup time split by country.

  • Environment: An environment represents the highest grouping of data you want to combine and compare within. You should think about environments as you think of “development” vs “staging” vs “production.” Multiple websites/apps or video platforms can use the same environment, but we suggest not combining staging and production data.

  • Viewer Experience Score: A metric for quickly evaluating the overall performance of your video platform with a single number. It is composed of four Experience Category Scores, which track the four major categories of video performance - playback failures, startup time, rebuffering, and video quality - based on the relative impact to the viewer experience.

Upgrading from Beta

There are a handful of changes that we put in place since the initial release of the Beta version of our API. We said the API wouldn’t change much when moving out of beta. Probably shouldn’t have said that, our bad. The good news is, we think things are a lot cleaner now!

Authentication

Previous authentication was done via a custom beta-auth-token header. This method will still work until all of our customers have migrated to the new API, but moving forward you should use Access Tokens via Basic authentication to authenticate your API requests

Path Changes

The most apparent change is that the base URL for API actions for Data has changed to https://api.mux.com/data/v1, where previously it was https://api.mux.com/api/v1. This removes the repetition of api in the path, while enabling our API to serve more purposes than just data.

Next, because each Access Token implicitly has access to only one Environment, all API routes no longer require you to enter /properties/:property_id. This results in shorter API URLs, and less bloat.

Missing Paths

You might have noticed that some of the previously documented routes are gone now. In order to focus the API around programmatic access to your analytics data, we’ve moved most of the account/organization management routes to be “UI only”. This means that an Access Token can’t do things like create/modify environments or add a new user to an organization. If you feel that some functionality was removed that you want back, let us know! We want to make sure our API is as helpful as possible, so we’re happy to revisit what’s programmatically accessible.


Breakdown

List breakdown values

GET https://api.mux.com/data/v1/metrics/video_startup_time/breakdown?filters[]=operating_system:windows&group_by=operating_system&limit=100&measurement=median&order_by=negative_impact&order_direction=desc&page=1&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic YzRmMmNkZWYtOTZmMy00ZGExLWFhZTUtMTg4ZTBiMTllNDMzOjNnV1JzaVptY3AvT1pWamlCeXFJbU50b2RHSzZZazliWmZEdHg0cXl3ZDBKTE9odE5pSU51K0NsUC9DL1FwVFJmaFQxcWRYaUtqSA==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: nr2ap3hdguds2t2t5kgpfue9ei1lcmrb
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 2,
  "timeframe": [
    1516241988,
    1516501188
  ],
  "data": [
    {
      "views": 3,
      "value": 3500,
      "total_watch_time": 7500,
      "negative_impact": 1,
      "field": "mac"
    },
    {
      "views": 2,
      "value": 1000,
      "total_watch_time": 3500,
      "negative_impact": 2,
      "field": "windows"
    }
  ]
}

List breakdown values
GET/data/v1/metrics/{metric_id}/breakdown{?filters,group_by,limit,measurement,order_by,order_direction,page,timeframe}

List the breakdown values for a specific metric

The value returned in views represents the total number of views that are applicable to the metric supplied; some metrics may report different view counts, if there are views that lack any information about the metric. For instance, in the case that we cannot retrieve player or video size we will not have upscaling and downscaling percentages, nor will we have a Quality Score. One specific example of this is that the value in views for video_upscale_percentage may be lower than the values for some other metrics, such as error_rate.

In the case that you request the error_rate for a specific error (by providing &error= in the parameters), the value in views represents the number of views that encountered that error during playback.

URI Parameters
metric_id
string (required) Example: video_startup_time

Metric name

Choices: 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 rebuffer_count rebuffer_duration rebuffer_frequency rebuffer_percentage rebuffer_score requests_for_first_preroll seek_latency startup_time_score upscale_percentage video_quality_score video_startup_preroll_load_time video_startup_preroll_request_time video_startup_time viewer_experience_score

group_by
string (required) Example: operating_system

Breakdown value to group the results by

Choices: asn browser browser_version cdn country experiment_name operating_system operating_system_version player_name player_software player_software_version player_version preroll_ad_asset_hostname preroll_ad_tag_hostname preroll_played preroll_requested source_hostname source_type stream_type sub_property_id video_series video_title

measurement
string (optional) Example: median

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

Choices: 95th median avg

filters
array (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

limit
integer (optional) Default: 100 Example: 100

Number of entries to return in response

page
integer (optional) Default: 1 Example: 1

Page number

order_by
string (optional) Default: negative_impact Example: negative_impact

Value to order the results by

Choices: negative_impact value views field

order_direction
string (optional) Default: desc Example: desc

Sort order

Choices: asc desc

timeframe
array (optional) Default: 24:hours Example: 24:hours

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.


Comparison

List all metric values

GET https://api.mux.com/data/v1/metrics/comparison?dimension=browser&filters[]=operating_system:windows&timeframe[]=24:hours&value=Safari
Requests200
Headers
accept: application/json
authorization: Basic NzRkNGQzOTEtNTA1YS00YWYwLThjZjMtZmRiNzhmYTNmODhhOjgwQlhWbVdwVnNrczdWRDNuTGxtQTZHU2psNWF5aFBUUkluVExiR3RkU1RKb2lRSGp5bjkzNXB2dDdkc210QklRbUJGeVpyeGM2aw==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: qv63os0oiqitgcvkhnaofgdtuuat0s36
server: Mux API Server v1.19.2
Body
{
  "total_row_count": null,
  "timeframe": [
    1516241921,
    1516501121
  ],
  "data": [
    {
      "watch_time": 32000,
      "view_count": 2,
      "name": "totals"
    },
    {
      "value": 0.25,
      "type": "score",
      "name": "Overall Score",
      "metric": "viewer_experience_score"
    },
    {
      "value": 1,
      "type": "score",
      "name": "Playback Failure Score",
      "metric": "playback_failure_score",
      "items": [
        {
          "value": 0,
          "type": "percentage",
          "name": "Playback Failure Percentage",
          "metric": "playback_failure_percentage"
        }
      ]
    },
    {
      "value": 1,
      "type": "score",
      "name": "Startup Time Score",
      "metric": "startup_time_score",
      "items": [
        {
          "value": 1000,
          "type": "milliseconds",
          "name": "Video Startup Time (median)",
          "metric": "video_startup_time",
          "measurement": "median"
        },
        {
          "value": 1000,
          "type": "milliseconds",
          "name": "Video Startup Time (95th %)",
          "metric": "video_startup_time",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Player Startup Time (median)",
          "metric": "player_startup_time",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Player Startup Time (95th %)",
          "metric": "player_startup_time",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Page Load Time (median)",
          "metric": "page_load_time",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Page Load Time (95th %)",
          "metric": "page_load_time",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Aggregate Startup Time (median)",
          "metric": "aggregate_startup_time",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Aggregate Startup Time (95th %)",
          "metric": "aggregate_startup_time",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "milliseconds",
          "name": "Seek Latency",
          "metric": "seek_latency"
        },
        {
          "value": 0,
          "type": "percentage",
          "name": "Exits Before Video Start",
          "metric": "exits_before_video_start"
        }
      ]
    },
    {
      "value": 0.25,
      "type": "score",
      "name": "Rebuffer Score",
      "metric": "rebuffer_score",
      "items": [
        {
          "value": 0,
          "type": "percentage",
          "name": "Rebuffer Percentage",
          "metric": "rebuffer_percentage"
        },
        {
          "value": 13.125,
          "type": "per_minute",
          "name": "Rebuffer Frequency",
          "metric": "rebuffer_frequency"
        },
        {
          "value": 0,
          "type": "milliseconds",
          "name": "Rebuffer Duration (median)",
          "metric": "rebuffer_duration",
          "measurement": "median"
        },
        {
          "value": 0,
          "type": "milliseconds",
          "name": "Rebuffer Duration (95th %)",
          "metric": "rebuffer_duration",
          "measurement": "95th"
        },
        {
          "value": 2,
          "type": "number",
          "name": "Rebuffer Count (median)",
          "metric": "rebuffer_count",
          "measurement": "median"
        },
        {
          "value": 5,
          "type": "number",
          "name": "Rebuffer Count (95th %)",
          "metric": "rebuffer_count",
          "measurement": "95th"
        }
      ]
    },
    {
      "value": null,
      "type": "score",
      "name": "Video Quality Score",
      "metric": "video_quality_score",
      "items": [
        {
          "value": null,
          "type": "percentage",
          "name": "Upscale Percentage (median)",
          "metric": "upscale_percentage",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Upscale Percentage (95th %)",
          "metric": "upscale_percentage",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Upscale Percentage (average)",
          "metric": "upscale_percentage",
          "measurement": "avg"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Downscale Percentage (median)",
          "metric": "downscale_percentage",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Downscale Percentage (95th %)",
          "metric": "downscale_percentage",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Downscale Percentage (average)",
          "metric": "downscale_percentage",
          "measurement": "avg"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Max Upscale Percentage (median)",
          "metric": "max_upscale_percentage",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Max Upscale Percentage (95th %)",
          "metric": "max_upscale_percentage",
          "measurement": "95th"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Max Downscale Percentage (median)",
          "metric": "max_downscale_percentage",
          "measurement": "median"
        },
        {
          "value": null,
          "type": "percentage",
          "name": "Max Downscale Percentage (95th %)",
          "metric": "max_downscale_percentage",
          "measurement": "95th"
        }
      ]
    }
  ]
}

List all metric values
GET/data/v1/metrics/comparison{?dimension,filters,timeframe,value}

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

Requires authentication

URI Parameters
timeframe
array (optional) Default: 24:hours Example: 24:hours

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 (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

dimension
string (optional) Example: browser

Dimension the specified value belongs to

Choices: asn browser browser_version cdn country experiment_name operating_system operating_system_version player_name player_software player_software_version player_version preroll_ad_asset_hostname preroll_ad_tag_hostname preroll_played preroll_requested source_hostname source_type stream_type sub_property_id video_series video_title

value
string (required) Example: Safari

Value to show all available metrics for


Export

List property video view export links

GET https://api.mux.com/data/v1/exports
Requests200
Headers
accept: application/json
authorization: Basic NWQxN2U3YzgtYjgyNy00NWE2LTkxZjAtZGE1MmY4MWMxMjkyOnlhWU5Td0I3VmtuSGRSUG05a2l4ZVBRMEpNT0x1NUI0a2FuZ2UvZkR6VzJlaDB1dHpwd0dMczVSNlg2QkR4OGtJUUVYbXY2VFdWRQ==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: 1625rnv9tcp24n9h1l7f17rfr864q4ca
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 2,
  "timeframe": [
    1516328401,
    1516414801
  ],
  "data": [
    "https://s3.amazonaws.com/mux-data-exports-test/10942/2017_10_1.csv.gz?signature=asdf1234",
    "https://s3.amazonaws.com/mux-data-exports-test/10942/2017_10_2.csv.gz?signature=asdf1234"
  ]
}

List property video view export links
GET/data/v1/exports

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

Requires that your plan has access to this specific feature. Reach out to us if you have questions.


Filter

List all available filters

GET https://api.mux.com/data/v1/filters
Requests200
Headers
accept: application/json
authorization: Basic YzE4Yjg4MTItNjVhZi00Yjg2LWJlMmYtYWMxOGZiNGM3ZDI4OndaUDZHaXg1NFoxLzNjRElKTUNKcmM5VUNhaHltb0YxbDQ4c2JlakZIbG1VQWV0VUlsWkRzdkdLbmpySzNVRzNkdWZFSXdyeDdJMg==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: sch408nk09ar5340cuurhs07tgj4jovo
server: Mux API Server v1.19.2
Body
{
  "total_row_count": null,
  "timeframe": [
    1516328397,
    1516414797
  ],
  "data": {
    "basic": [
      "browser",
      "country",
      "operating_system",
      "player_software",
      "player_software_version",
      "source_hostname",
      "source_type",
      "stream_type",
      "video_title"
    ],
    "advanced": [
      "asn",
      "browser_version",
      "cdn",
      "experiment_name",
      "operating_system_version",
      "player_name",
      "player_version",
      "preroll_ad_asset_hostname",
      "preroll_ad_tag_hostname",
      "preroll_played",
      "preroll_requested",
      "sub_property_id",
      "video_series"
    ]
  }
}

List all available filters
GET/data/v1/filters

Lists all the filters broken out into basic and advanced


List the values for a specific filter

GET https://api.mux.com/data/v1/filters/browser?filters[]=operating_system:windows&limit=100&page=1&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic ODkxYzIzODAtYmY5Ni00MTRlLWJiMjctN2I3MTE0YjhkMDJhOmIrUWgyL251SWlZR0xNQlBRT1hIclRlZHJkdm1PYTNwTUFDUDlhUGFyaXc0cmhNSVlFSGtDY0ZHOWRIcExTb2YzNGlwbE8yRi9Mcg==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: 3dmhc1kg24vcm3pnav8a04f6t0443595
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 2,
  "timeframe": [
    1516241996,
    1516501196
  ],
  "data": [
    {
      "value": "Foo Bar Bat Baz",
      "total_count": 2
    },
    {
      "value": "Trump fights Manbearpig IRL",
      "total_count": 1
    }
  ]
}

List the values for a specific filter
GET/data/v1/filters/{id}{?filters,limit,page,timeframe}

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

Requires authentication

URI Parameters
id
string (required) Example: browser

The name of the filter to retrieve possible values for

Choices: asn browser browser_version cdn country experiment_name operating_system operating_system_version player_name player_software player_software_version player_version preroll_ad_asset_hostname preroll_ad_tag_hostname preroll_played preroll_requested source_hostname source_type stream_type sub_property_id video_series video_title

timeframe
array (optional) Default: 24:hours Example: 24:hours

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 (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

page
integer (optional) Default: 1 Example: 1

Page number

limit
integer (optional) Default: 100 Example: 100

Number of entries to return in response


Insight

List insights

GET https://api.mux.com/data/v1/metrics/video_startup_time/insights?measurement=median&order_direction=desc&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic OTg4MjM1MmYtYTgyOS00OTI1LTgwZmItNGM3NmM1NjZkYTVjOi9KQUtQRGx0MkJLelF3Q3hoR3FraFUxY1I1SWFoVThnRDBPSG8rcVFIaWJLRGgxbU9yNUMzYW1LR3o4eTlQT2VYNi84R1BpRkpLNw==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: 6se57vkgbld2jdpojfd6if4bd71g2ae4
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 2,
  "timeframe": [
    1500389723,
    1500648923
  ],
  "data": [
    {
      "total_watch_time": 10000,
      "total_views": 5,
      "total_row_count": 1,
      "negative_impact_score": 0.6,
      "metric": 4000,
      "filter_value": "US",
      "filter_column": "country"
    }
  ]
}

List insights
GET/data/v1/metrics/{metric_id}/insights{?measurement,order_direction,timeframe}

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.

Requires authentication

URI Parameters
metric_id
string (required) Example: video_startup_time

Metric name

Choices: 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 rebuffer_count rebuffer_duration rebuffer_frequency rebuffer_percentage rebuffer_score requests_for_first_preroll seek_latency startup_time_score upscale_percentage video_quality_score video_startup_preroll_load_time video_startup_preroll_request_time video_startup_time viewer_experience_score

measurement
string (optional) Example: median

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

Choices: 95th median avg

order_direction
string (optional) Default: desc Example: desc

Sort order

Choices: asc desc

timeframe
array (optional) Default: 24:hours Example: 24:hours

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.


Overall

Return overall values

GET https://api.mux.com/data/v1/metrics/video_startup_time/overall?filters[]=operating_system:windows&measurement=median&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic NTA0OTAxNDYtNWVhYi00ZThhLWExYTUtZWE5ODFkMTJhMGViOkIweU5PZGhRcEd4NTBGbW5XbzZETlRlM0tkNmZheDVKWjh4STExbkdHQlFlUzZMTVlNaVZEWDd0SXFOT1V5SkRnSUFNU2JhWkhQbA==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: 5vpuc01rh450tg69j2c9a5a9shlrla71
server: Mux API Server v1.19.2
Body
{
  "total_row_count": null,
  "timeframe": [
    1516241946,
    1516501146
  ],
  "data": {
    "value": 0.8333333333333334,
    "total_watch_time": 3000,
    "total_views": 3,
    "global_value": null
  }
}

Return overall values
GET/data/v1/metrics/{metric_id}/overall{?filters,measurement,timeframe}

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.

Requires authentication

URI Parameters
metric_id
string (required) Example: video_startup_time

Metric name

Choices: 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 rebuffer_count rebuffer_duration rebuffer_frequency rebuffer_percentage rebuffer_score requests_for_first_preroll seek_latency startup_time_score upscale_percentage video_quality_score video_startup_preroll_load_time video_startup_preroll_request_time video_startup_time viewer_experience_score

timeframe
array (optional) Default: 24:hours Example: 24:hours

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 (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

measurement
string (optional) Example: median

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

Choices: 95th median avg


Timeseries

Get metric timeseries data

GET https://api.mux.com/data/v1/metrics/video_startup_time/timeseries?filters[]=operating_system:windows&group_by=hour&measurement=median&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic NjE2NmFmODAtOGY3ZC00ODM3LTg1ZTgtN2M2YTk2YmFmNWFkOjNtK1BIeURYTTlNTVhWNTlkaTgzelpmbTVhT3VHUHBsTUtlb3U0OTVvZ091RGl3THZhYlJ3WDZ3Z1JQWm5aZWFkMzI5N1FiTzEzag==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: gecrc1mnqnvqna8ad01j2ba76e8b6mgu
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 73,
  "timeframe": [
    1516241947,
    1516501147
  ],
  "data": [
    [
      "2018-01-18T02:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T03:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T04:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T05:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T06:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T07:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T08:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T09:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T10:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T11:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T12:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T13:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T14:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T15:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T16:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T17:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T18:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T19:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T20:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T21:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T22:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-18T23:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T00:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T01:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T02:00:00.000Z",
      0,
      2
    ],
    [
      "2018-01-19T03:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T04:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T05:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T06:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T07:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T08:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T09:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T10:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T11:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T12:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T13:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T14:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T15:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T16:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T17:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T18:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T19:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T20:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T21:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T22:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-19T23:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T00:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T01:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T02:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T03:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T04:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T05:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T06:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T07:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T08:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T09:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T10:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T11:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T12:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T13:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T14:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T15:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T16:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T17:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T18:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T19:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T20:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T21:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T22:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-20T23:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-21T00:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-21T01:00:00.000Z",
      null,
      null
    ],
    [
      "2018-01-21T02:00:00.000Z",
      null,
      null
    ]
  ]
}

Get metric timeseries data
GET/data/v1/metrics/{metric_id}/timeseries{?filters,group_by,measurement,timeframe}

Returns timeseries data for a specific metric

Requires authentication

URI Parameters
metric_id
string (required) Example: video_startup_time

Metric name

Choices: 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 rebuffer_count rebuffer_duration rebuffer_frequency rebuffer_percentage rebuffer_score requests_for_first_preroll seek_latency startup_time_score upscale_percentage video_quality_score video_startup_preroll_load_time video_startup_preroll_request_time video_startup_time viewer_experience_score

timeframe
array (optional) Default: 24:hours Example: 24:hours

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 (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

measurement
string (optional) Example: median

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

Choices: 95th median avg

group_by
string (optional) Example: hour

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

Choices: hour day


Video view

List video views

GET https://api.mux.com/data/v1/video-views?error_id=error_id:any&filters[]=operating_system:windows&limit=100&order_direction=desc&page=1&timeframe[]=24:hours&viewer_id=ABCD1234
Requests200
Headers
accept: application/json
authorization: Basic ODkzZmMxMDctMWZhMC00MTE0LWI3NzctZTQzMDVkMmQwZDM3OlZKM2wxK1BsamVOS1FuTy8wbFZYMDJPbHk4Yzhsc3l0aENyNktha2ZrU0dnamdJZ01HdFhPbXZxdFcxZTJlWGhQbkl5VStKWUQxKw==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: pot2378ji7bn1l0vub4girqfh791nomm
server: Mux API Server v1.19.2
Body
{
  "total_row_count": 2,
  "timeframe": [
    1516241921,
    1516501121
  ],
  "data": [
    {
      "viewer_os_family": null,
      "viewer_application_name": "Chrome",
      "view_start": "2018-01-19T02:18:41.940Z",
      "view_end": "2018-01-19T02:18:41.940Z",
      "video_title": null,
      "total_row_count": 2,
      "player_error_message": null,
      "player_error_code": null,
      "id": "DEM1z65UMx6Ldcgq9tDR9tkJNTqlE5eNlN4",
      "error_type_id": 1087,
      "country_code": null
    },
    {
      "viewer_os_family": null,
      "viewer_application_name": "Chrome",
      "view_start": "2018-01-19T02:18:41.940Z",
      "view_end": "2018-01-19T02:18:41.940Z",
      "video_title": null,
      "total_row_count": 2,
      "player_error_message": null,
      "player_error_code": null,
      "id": "k8n4aklUyrRDekILDWta1qSJqNFpYB7N50",
      "error_type_id": 1088,
      "country_code": null
    }
  ]
}

List video views
GET/data/v1/video-views{?error_id,filters,limit,order_direction,page,timeframe,viewer_id}

Returns a list of video views for a property that occurred within the specified timeframe. Results are ordered by view_end, according to what you provide for order_direction.

Requires authentication

Due to the size of each video view object, the results in the view list only contain a subset of the details

URI Parameters
filters
array (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

error_id
integer (optional) Example: error_id:any

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.

viewer_id
string (required) Example: ABCD1234

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

limit
integer (optional) Default: 100 Example: 100

Number of entries to return in response

page
integer (optional) Default: 1 Example: 1

Page number

order_direction
string (optional) Default: desc Example: desc

Sort order

Choices: asc desc

timeframe
array (optional) Default: 24:hours Example: 24:hours

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.


Single view

GET https://api.mux.com/data/v1/video-views/ABCD1234
Requests200
Headers
accept: application/json
authorization: Basic YTI0MGZmN2MtOTdiOC00ZGZlLWIwZjItMGE5YWNhY2RjZDJlOktWa1hMTDJLL1FpQit3VkgvaG9ZRWpSaDVXWTZRY01zRnFMbzFjQStoYmpaSlFRN3NscFNiV3hsdy9FR2xvSGxaeUcvblJyUlB3Rg==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: gbs8i0vh9bvhbapn9bmdo6qq8ovd3ih6
server: Mux API Server v1.19.2
Body
{
  "total_row_count": null,
  "timeframe": [
    1516241921,
    1516501121
  ],
  "data": {
    "view_seek_duration": null,
    "video_language": null,
    "viewer_os_family": null,
    "viewer_user_agent": null,
    "player_error_code": null,
    "player_height": null,
    "player_poster": null,
    "time_to_first_frame": null,
    "player_source_type": null,
    "video_stream_type": null,
    "cdn": null,
    "buffering_rate": null,
    "metro": null,
    "player_instance_id": "123",
    "viewer_application_version": "8",
    "updated_at": "2018-01-20T02:19:15.000Z",
    "player_source_host_name": null,
    "preroll_played": false,
    "player_source_duration": null,
    "view_total_downscaling": null,
    "player_source_stream_type": null,
    "continent_code": null,
    "view_error_id": null,
    "page_load_time": null,
    "video_variant_id": null,
    "view_id": "123",
    "watch_time": null,
    "isp": null,
    "inserted_at": "2018-01-20T02:19:15.000Z",
    "viewer_application_name": "Safari",
    "exit_before_video_start": false,
    "view_seek_count": null,
    "player_software": null,
    "player_preload": false,
    "asn": null,
    "view_end": "2018-01-19T02:18:41.940Z",
    "events": [],
    "video_startup_preroll_request_time": null,
    "view_total_content_playback_time": null,
    "buffering_duration": null,
    "requests_for_first_preroll": null,
    "player_width": null,
    "page_url": "http://example.com/foo/bar",
    "preroll_ad_tag_hostname": null,
    "session_id": "123",
    "viewer_os_architecture": null,
    "page_type": null,
    "view_max_downscale_percentage": null,
    "preroll_ad_asset_hostname": null,
    "video_variant_name": null,
    "experiment_name": null,
    "watched": false,
    "mux_api_version": null,
    "player_load_time": null,
    "preroll_requested": false,
    "region": null,
    "player_error_message": null,
    "country_code": null,
    "player_source_domain": null,
    "longitude": null,
    "player_name": null,
    "video_producer": null,
    "video_series": null,
    "country_name": null,
    "rebuffer_percentage": null,
    "used_fullscreen": false,
    "video_encoding_variant": null,
    "player_language": null,
    "viewer_device_manufacturer": null,
    "view_start": "2018-01-19T02:18:41.940Z",
    "latitude": null,
    "viewer_device_category": null,
    "video_id": null,
    "player_source_width": null,
    "property_id": 10185,
    "city": null,
    "player_software_version": null,
    "player_autoplay": false,
    "video_duration": null,
    "buffering_count": null,
    "view_max_upscale_percentage": null,
    "platform_summary": "Safari",
    "viewer_application_engine": null,
    "mux_embed_version": null,
    "error_type_id": null,
    "id": "7a2e4405-a646-4439-8261-785d9c011470",
    "player_version": null,
    "player_startup_time": null,
    "player_source_url": null,
    "view_total_upscaling": null,
    "short_time": " 2:18am UTC 2018-01-19",
    "viewer_user_id": null,
    "player_mux_plugin_version": null,
    "video_title": null,
    "mux_viewer_id": "123",
    "viewer_device_name": null,
    "viewer_os_version": null,
    "video_content_type": null,
    "player_view_count": null,
    "player_source_height": null,
    "video_startup_preroll_load_time": null,
    "platform_description": null
  }
}

Single view
GET/data/v1/video-views/{id}

Returns the details for a single video view

Requires authentication

URI Parameters
id
string (required) Example: ABCD1234

Single view ID


View error

List playback errors

GET https://api.mux.com/data/v1/errors?filters[]=operating_system:windows&timeframe[]=24:hours
Requests200
Headers
accept: application/json
authorization: Basic N2JlYzNiOTMtNmU1Yi00ODI0LWE1YWQtZWU3ZWNlZWJlZmM1OitVZVQ2b3FrYVhGYUNYWHVjS0tiakRXNXFOYmplb1pIWDBpcGNxUDJ6UDR4MVc3bm5NV2EvTGNxaGpIdmJLZWVyZlNsWjZIM1hOMQ==
Responses200
Headers
Content-Type: application/json; charset=utf-8
cache-control: max-age=0, private, must-revalidate
x-request-id: 90k6jnbo3ab3resdloimlu8i5bmvvdce
server: Mux API Server v1.19.2
Body
{
  "total_row_count": null,
  "timeframe": [
    1516328328,
    1516414728
  ],
  "data": [
    {
      "percentage": 0.6666666666666666,
      "notes": "This is a really crazy note",
      "message": "This is a message for this crazy error",
      "last_seen": "2018-01-20T01:18:48.054Z",
      "id": 1121,
      "description": "If we're going to understand this error, first we need to understand life itself.",
      "count": 2,
      "code": 1
    },
    {
      "percentage": 0.3333333333333333,
      "notes": "This is a really crazy note",
      "message": "This is a message for this crazy error",
      "last_seen": "2018-01-19T23:18:48.054Z",
      "id": 1120,
      "description": "If we're going to understand this error, first we need to understand life itself.",
      "count": 1,
      "code": 3
    }
  ]
}

List playback errors
GET/data/v1/errors{?filters,timeframe}

Returns a list of playback errors

Requires authentication

URI Parameters
filters
array (optional) Example: operating_system:windows

Filter key:value pairs. Must be provided as an array query string parameter (e.g. filters[]=operating_system:windows&filters[]=country:US). Possible filter names are the same as returned by the List Filters endpoint.

timeframe
array (optional) Default: 24:hours Example: 24:hours

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.


Last generated by on 20 Jan 2018