Skip to Content
Mux Docs: Home
List Video Views
get

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

curl https://api.mux.com/data/v1/video-views?timeframe[]=7:days \
  -X GET \
  -d '{ "limit": 5 }' \
  -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

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

Filter results using key:value pairs. Must be provided as an array query string parameter.

Basic filtering:

  • filters[]=dimension:value - Include rows where dimension equals value
  • filters[]=!dimension:value - Exclude rows where dimension equals value

For trace dimensions (like video_cdn_trace):

  • filters[]=+dimension:value - Include rows where trace contains value
  • filters[]=-dimension:value - Exclude rows where trace contains value
  • filters[]=dimension:[value1,value2] - Exact trace match

Examples:

  • filters[]=country:US - US views only
  • filters[]=+video_cdn_trace:fastly - Views using Fastly CDN
metric_filters[]
array

Limit the results to rows that match inequality conditions from provided metric comparison clauses. Must be provided as an array query string parameter.

Possible filterable metrics are the same as the set of metric ids, with the exceptions of exits_before_video_start, unique_viewers, video_startup_failure_percentage, view_dropped_percentage, and views.

Example:

  • metric_filters[]=aggregate_startup_time>=1000
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_experience_score": 0.8,
      "watch_time": 1000,
      "playback_failure": false
    },
    {
      "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_experience_score": 0.8,
      "watch_time": 1000,
      "playback_failure": false
    },
    {
      "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_experience_score": 0.8,
      "watch_time": 1000,
      "playback_failure": true
    },
    {
      "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",
      "viewer_experience_score": 0.8,
      "watch_time": 1000,
      "playback_failure": false
    }
  ]
}