Export raw video view data

Understand how to export your video views data into your own data warehouse for processing and analysis.

In this guide:

Call the Export API to get daily aggregated data

The Export API will return a list of CSV files (one per day) that contain each video view.

Stream views as they complete

Export video view data as the views complete.

Understand the data fields

Understand the data fields that Mux attaches to each view.

CSV file formats

Samples of the CSV file formats

Streaming Export message format

View data can be exported from Mux Data for aggregation and reporting in your data infrastructure. Views are available individually using the Views APIAPI or in bulk with the export methods: daily CSV exports or streaming exports.

Call the Export API to get daily aggregated data

Full data exports are available via the Exports APIAPI. This API is available for Mux Data customers on Media plan.

Use this API to get a list of CSV files available for download. Files are available to download for seven days after they are generated. Each CSV file is a single day of data and includes every single dimension collected by Mux, for each single video view. The table below details each of these data fields.

The Versions column indicates what fields are included in each version. Newer export versions will include the latest columns available. Some columns may be empty based on the features enabled. From version 2 onward, fields are sorted in alphabetical order. Older versions of the export may have fields in a different order, please refer to the export file for the most accurate ordering. Please contact support to change the export version that is generated.

We strongly suggest you build the file import to use the field names rather than ordinal order so additional fields can be added to the file without causing an error.

Stream views as they complete

Streaming Exports are only available on Mux Data Media plans.

Mux Data supports streaming exports of video views to an Amazon Kinesis Data Stream or Google Cloud Pub/Sub topic in your cloud account. Views are sent to Kinesis or Pub/Sub as they complete and are made available to retrieve from the stream within about one minute after the view ends.

Each message is a single view, with all of the metadata and metrics, and the event timeline for the view. The view data can be stored in your long-term storage for aggregation and reporting.

This method of access is most useful for customers who want to update metrics on a rolling basis throughout the day or are embedding metrics in a user-facing application feature and need faster updates than once per day.

Setting up a streaming export

Streaming exports can be configured in the Streaming Exports settings in your Mux dashboard. See the setup guide for your platform for more information on setting up an export:

Message format

Messages are formatted using Protobuf (proto2) encoding. Every message uses the VideoView message type defined in the export Protobuf spec, which is available in the mux-protobuf repository. Use the latest Protobuf spec when creating schemas or generating code.

The fields in the Protobuf definition match those used in the latest version of the Exports API. The available fields are noted in the table below.

View handling

A view can be updated after it has been exported. This will be expressed with a record of the latest version of the view being emitted to the stream. When processing views, make sure you're able to handle multiple or duplicate records for each view ID (view_id). The view_id can be used as a unique primary key for each view record.

Understand the data fields

Mux API Value: field name in the CSV file or streaming export

Unit: unit of the field, such as text, percentage, or bits per second

Type:

Dimension: metadata about the view
Metric: metrics calculated by Mux
Score: score calculated by Mux

Versions: export version in which the fields are included

Mux API Value	Unit	Type	Definition	Versions
`asn`	Integer	Dim.	Autonomous System Number uniquely identifying each network	v1+
`asset_id`	Text	Dim.	If Mux Video is used, the Asset Id of the video.	v4+
`browser`	Text	Dim.	Browser used for the video view (Safari, Chrome, etc.).	v2+
`browser (viewer_application_name)`	Text	Dim.	Deprecated - see `browser`	v1
`browser_version`	Version	Dim.	Browser version (e.g. 66.0.3359.158).	v2+
`browser_version (viewer_application_version)`	Version	Dim.	Deprecated - see `browser_version (viewer_application_version)`	v1
`cdn`	Text	Dim.	CDN delivering the video view (either determined by Mux (network metrics), or provided as video_cdn (Custom Metadata).	v1+
`city`	Text	Dim.	City of the viewer.	v1+
`continent_code`	ISO Code	Dim.	2-letter ISO code identifying the Continent of the viewer (e.g. NA, EU).	v1+
`country`	ISO Code	Dim.	2-letter Country Code.	v2+
`country (country_code)`	ISO Code	Dim.	Deprecated - see `country`	v1
`country_name`	Text	Dim.	Country of the viewer.	v1+
`custom_1`	Text	Dim.	Customer-defined metadata.	v2+
`custom_2`	Text	Dim.	Customer-defined metadata.	v2+
`custom_3`	Text	Dim.	Customer-defined metadata.	v2+
`custom_4`	Text	Dim.	Customer-defined metadata.	v2+
`custom_5`	Text	Dim.	Customer-defined metadata.	v2+
`environment_id`	Unique ID	Dim.	Mux Environment ID, linked with a specific environment	v4+
`error_type`	Unique ID	Dim.	Mux-internal ID used to categorize errors.	v2+
`error_type (error_type_id)`	Unique ID	Dim.	Deprecated - see `error_type`	v1
`exit_before_video_start`	Boolean	Metric	Identifies when a viewer abandons the video because it is taking too long to load.	v1+
`experiment_name`	Text	Dim.	(Custom Metadata) A/B Testing: use this field to separate views into different experiments.	v1+
`isp`	Text	Dim.	Unused	v1+
`latitude`	Degrees	Dim.	Latitude of the viewer, truncated to 1 decimal place.	v1+
`live_stream_id`	Text	Dim.	If Mux Video is used, the Live Stream Id of the video.	v4+
`live_stream_latency`	Integer	Metric	Live Stream Latency measuring the average time from ingest to display for the view.	v4+
`longitude`	Degrees	Dim.	Longitude of the viewer, truncated to one decimal place.	v1+
`max_downscale_percentage`	Percentage	Metric	Maximum Downscale Percentage at any point in time during a video view.	v2+
`max_downscale_percentage (view_max_downscale_percentage)`	Percentage	Metric	Deprecated - see `max_downscale_percentage`	v1
`max_upscale_percentage`	Percentage	Metric	Maximum Upscale Percentage at any point in time during a video view.	v2+
`max_upscale_percentage (view_max_upscale_percentage)`	Percentage	Metric	Deprecated - see `max_upscale_percentage`	v1
`metro`	Text	Dim.	Unused	v1+
`mux_api_version`	Text	Dim.	Ignore	v1+
`mux_embed_version`	Dim.	Dim.	Internal version of Mux Core SDK. Ignore	v1+
`mux_viewer_id`	Unique ID	Dim.	A Mux Internal ID representing the viewer who is watching the stream.	v1+
`operating_system`	Text	Dim.	Operating System (iOS, Windows, etc).	v2+
`operating_system (viewer_os_family)`	Text	Dim.	Deprecated - see `operating_system`	v1
`operating_system_version`	Version	Dim.	Operating System version (e.g. 10.15).	v2
`operating_system_version (viewer_os_version)`	Version	Dim.	Deprecated - see `operating_system_version`	v1
`page_load_time`	Milliseconds	Metric	Measures the time from the initial user request for a page to the time when the video player is first initialized	v1+
`page_type`	Text	Dim.	(Custom Metadata) Provides the context of the page for more specific analysis. Values include `watchpage` or `iframe`.	v1+
`page_url`	URL	Dim.	Page URL	v1+
`platform_description`	Text	Dim.	Unused	v1+
`playback_id`	Text	Dim.	If Mux Video is used, the Playback Id of the video.	v4+
`playback_success_score`	Decimal	Dim.	Playback Success Score	v2+
`player_autoplay`	Boolean	Dim.	Indicates whether the player autoplayed the video or not	v1+
`player_error_code`	String	Dim.	An error code that represents a fatal error (one resulting in playback failure). Often an integer, but implementation-dependent.	v1+
`player_error_message`	Text	Dim.	Message sent by the player when an error has been fired up (associated with an error code)	v1+
`player_height`	Integer	Dim.	Height of the player as displayed in page, in pixels	v1+
`player_instance_id`	Unique ID	Dim.	Identifies the instance of the Player class that is created when a video is initialized	v1+
`player_language`	Text	Dim.	Player's text language	v1+
`player_load_time`	Milliseconds	Metric	Deprecated - see `player_startup_time`)	v1+
`player_mux_plugin_name`	Text	Dim.	Mux Integration Plugin name (e.g. mux-player)	v1+
`player_mux_plugin_version`	Version	Dim.	Mux Integration Plugin version (e.g. 2.2.0)	v2+
`player_name`	Text	Dim.	(Custom Metadata) Identifies different configurations or types of players around your site or application	v1+
`player_poster`	URL	Dim.	The image shown as the pre-visualisation before play	v1+
`player_preload`	Boolean	Dim.	Specifies if the player was configured to load the video when the page loads.	v1+
`player_remote_played`	Boolean	Dim.	Specify from the SDK if the video is remote played to AirPlay or Chromecast.	v2+
`player_software`	Text	Dim.	Player Software being used to play the Video (e.g. Video.js, JW Player, etc.)	v1+
`player_software_version`	Text	Dim.	Player Software Version (e.g. 2.45.5)	v1+
`player_source_domain`	Text	Dim.	Video Source Domain (e.g. myvideostreams.com)	v1+
`player_source_duration`	Milliseconds	Dim.	Video Source Duration	v1+
`player_source_height`	Integer	Dim.	Height of the source video being sent to the player, in pixels	v1+
`player_source_stream_type`	Text	Dim.	Unused	v1+
`player_source_url`	URL	Dim.	Video Source URL	v1+
`player_source_width`	Integer	Dim.	Width of the source video being as seen by the player	v1+
`player_startup_time`	Milliseconds	Metric	Measures the time from when the player is first initialized in the page to when it is ready to receive further instructions.	v1+
`player_version`	Text	Dim.	(Custom Metadata) As you make changes to your player you can compare how new versions of your player perform by updating this value. This is not the player software version (e.g. Video.js 5.0.0), which is tracked automatically by the SDK.	v1+
`player_view_count`	Integer	Dim.	View Count - equal to 1 in Full Exports (1 line = 1 video view)	v1+
`player_width`	Integer	Dim.	Width of the player as displayed in page, in pixels	v1+
`property_id`	Unique ID	Dim.	Mux Property ID, linked with a specific environment. Deprecated, please use `environment_id`.	v1+
`rebuffer_count`	Integer	Metric	Number of rebuffering events that happen during the video view.	v2+
`rebuffer_count (buffering_count)`	Integer	Metric	Deprecated - see `rebuffer_count`	v1
`rebuffer_duration`	Milliseconds	Metric	Amount of time in milliseconds that viewers wait for rebuffering per video view.	v2+
`rebuffer_duration (buffering_duration)`	Milliseconds	Metric	Deprecated - see `rebuffer_duration`	v1
`rebuffer_frequency`	Events per millisecond	Metric	Measures how often rebuffering events happen.	v2+
`rebuffer_frequency (buffering_rate)`	Events per millisecond	Metric	Deprecated - see `rebuffer_frequency`	v1
`rebuffer_percentage`	Percentage	Metric	Volume of rebuffering that is occurring across the view	v1+
`region`	Text	Dim.	Region of the viewer	v1+
`session_id`	Unique ID	Dim.	Mux Session ID tracking a viewer's session	v1+
`smoothness_score`	Decimal	Score	Smoothness Score	v2+
`source_hostname`	Text	Dim.	Video Hostname (e.g. media.myvideos.com).	v2+
`source_hostname (player_source_host_name)`	Text	Dim.	Deprecated - see `source_hostname`	v1
`source_type`	Text	Dim.	Format of the source, as determined by the player. E.g. 'dash', 'application/x-mpegurl', 'video/mp4', etc.	v2+
`source_type (player_source_type)`	Text	Dim.	Deprecated - see `source_type`	v1
`startup_time_score`	Decimal	Score	Startup Time Score	v2+
`stream_type`	Text	Dim.	(Custom Metadata) 'live' or 'on-demand'.	v2+
`stream_type (video_stream_type)`	Text	Dim.	Deprecated - see `stream_type`	v1
`sub_property_id`	Text	Dim.	Sub Property Id	v2+
`time_to_first_frame`	Milliseconds	Metric	Deprecated - see `video_startup_time`	v1
`used_fullscreen`	Boolean	Dim.	Indicates whether the viewer used full screen to watch the video.	v1+
`video_content_type`	Text	Dim.	(Custom Metadata) Content Type (e.g. 'short', 'movie', 'episode', 'clip', 'trailer', or 'event').	v1+
`video_duration`	Milliseconds	Dim.	(Custom Metadata) The length of the video supplied to Mux via custom metadata	v1+
`video_encoding_variant`	Text	Dim.	(Custom Metadata) An optional detail that allows you to compare different encoding settings.	v1+
`video_id`	Unique ID	Dim.	(Custom Metadata) Your internal ID for the video	v1+
`video_language`	Text	Dim.	The audio language of the video, assuming it's unchangeable after playing.	v1+
`video_producer`	Text	Dim.	(Custom Metadata) The producer of the video title	v1+
`video_quality_score`	Decimal	Score	Video Quality Score	v2+
`video_series`	Text	Dim.	(Custom Metadata) example: 'Season 1'	v1+
`video_startup_time`	Milliseconds	Metric	(Video Startup Time on Mux Dashboards) Measures from when the player has been instructed to play the video, to when the first frame of video (either content or preroll ad) is showing and the playhead is progressing.	v2+
`video_title`	Text	Dim.	(Custom Metadata) Video Title	v1+
`video_variant_id`	Unique ID	Dim.	(Custom Metadata) Your internal ID for a video variant	v1+
`video_variant_name`	Text	Dim.	(Custom Metadata) An optional detail that allows you to monitor issues with the files of specific versions of the content, for example different audio translations or versions with hard-coded/burned-in subtitles.	v1+
`view_downscaling_percentage`	Percentage	Metric	Downscale Percentage	v2+
`view_end`	Time	Dim.	Date and Time at which the view ended.	v1+
`view_id`	Unique ID	Dim.	Unique View Identifier	v1+
`view_max_playhead_position`	Milliseconds	Dim.	The furthest the video was played, indicated by the maximum time value of the playhead during the view.	v3+
`view_playing_time`	Milliseconds	Metric	The amount of time the video spent playing during the view; this value does not include time spent joining, rebuffering, or seeking.	v3+
`view_seek_count`	Integer	Dim.	The number of times that the viewer attempted to seek to a new location within the view.	v1+
`view_seek_duration`	Milliseconds	Dim.	Total amount of time spent waiting for playback to resume after the viewer seeks to a new location. Seek Latency metric in the Dashboard is this value divided by `view_seek_count`.	v1+
`view_session_id`	Unique ID	Dim.	An id that can be used to correlate the view with platform services upstream such as CDN or origin logs.	v2+
`view_start`	Time	Dim.	Date and Time at which the view started.	v1+
`view_total_content_playback_time`	Milliseconds	Dim.	Internal metric used in calculating upscale and downscale percentages.	v1+
`view_total_downscaling`	Milliseconds	Dim.	Internal number used to calculate Downscale Percentage Metric. Downscale Percentage = `view_total_downscaling / view_total_content_playback_time`	v1+
`view_total_upscaling`	Milliseconds	Dim.	Internal number used to calculate Upscale Percentage Metric. Upscale Percentage = `view_total_upscaling / view_total_content_playback_time`	v1+
`view_upscaling_percentage`	Percentage	Metric	Upscale Percentage	v2+
`viewer_application_engine`	Text	Dim.	Web Browser Engine (Gecko, WebKit, etc)	v1+
`viewer_connection_type`	Text	Dim.	The type of network connection used by the device, where available (e.g. mobile, wired, wireless)	v2+
`viewer_device_category`	Text	Dim.	The type of device used (e.g. console, desktop, phone, tablet, TV)	v1+
`viewer_device_manufacturer`	Text	Dim.	Device Manufacturer (e.g. Apple, Microsoft)	v1+
`viewer_device_model`	Text	Dim.	Device Model (e.g. iPhone11,2)	v4+
`viewer_device_name`	Text	Dim.	Device Name (e.g. iPhone 12)	v1+
`viewer_experience_score`	Decimal	Score	Overall Viewer Experience Score	v2+
`viewer_os_architecture`	Text	Dim.	No longer used. Ignore.	v1+
`viewer_user_agent`	Text	Dim.	User Agent (e.g. `Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0)`)	v1+
`viewer_user_id`	Unique ID	Dim.	(Custom Metadata) A Customer-defined ID representing the viewer who is watching the stream. Note: You should not use any value that is personally identifiable such as email address, username, etc. Instead, you should supply an anonymized viewer ID which you have stored within your own system.	v1+
`watch_time`	Milliseconds	Dim.	Total Watch Time across the view (includes Startup Time, Playing time, potential rebuffering).	v1+
`watched`	Boolean	Dim.	Ignore	v1+
`weighted_average_bitrate`	bits/sec	Metric	Weighted Average Bitrate, expressed in bps.	v2+

Ad Metrics and Dimensions

Mux API Value	Unit	Type	Definition	Versions
`preroll_ad_asset_hostname`	Hostname	Dim.	Hostname of the Preroll Ad Asset.	v1+
`preroll_ad_tag_hostname`	Hostname	Dim.	Hostname of a Preroll Ad Tag.	v1+
`preroll_played`	Boolean	Dim.	Flag to identify video views for which a Preroll Ad has been successfully played.	v1+
`preroll_requested`	Boolean	Dim.	Flag to identify video views for which a Preroll Ad has been requested.	v1+
`requests_for_first_preroll`	Integer	Metric	Measures the number of ad requests that are made up to the point of preroll ad playback beginning.	v1+
`video_startup_preroll_load_time`	Milliseconds	Metric	Total amount of Video Startup Time that is spent loading the first preroll ad asset.	v1+
`video_startup_preroll_request_time`	Milliseconds	Metric	Total amount of Video Startup Time that is spent making preroll ad requests.	v1+

Request-level Metrics

Mux API Value	Unit	Type	Definition	Versions
`max_request_latency`	Milliseconds	Metric	Maximum time to first byte for a media request.	v2+
`max_request_latency (view_max_request_latency)`	Milliseconds	Metric	Deprecated - see `max_request_latency`	v1
`request_latency`	Milliseconds	Metric	Measures the average time to first byte for media requests.	v2+
`request_latency (view_average_request_latency)`	Milliseconds	Metric	Deprecated - see `request_latency`	v1
`request_throughput`	bits/sec	Metric	Measures the average throughput, in bits per second, for all media requests that were completed.	v2+
`request_throughput (view_average_request_throughput)`	bits/sec	Metric	Deprecated - see `request_throughput`	v1

CSV file formats

The daily CSV export files are generated based on the specific version that is configured and include the fields specified in the section above.

Sample CSV export files are available to download, for reference:

Streaming Export message format

The protobuf definition for Streaming Exports of video views is available in the mux-protobuf repository. Please subscribe to this repository for updates to the protobuf definition.