Skip to Content
Mux Docs: Home

Export raw video view data

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

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 in either JSON format or Protobuf (proto2) encoding. You can choose between the two formats when setting up the streaming export in the Mux Dashboard -> Settings -> Streaming Export -> New streaming export page.

For Protobuf 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. Note that all units of type Time are represented as timestamps in UTC.

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 ValueUnitTypeDefinitionVersions
asnIntegerDim.Autonomous System Number uniquely identifying each networkv1+
asset_idTextDim.If Mux Video is used, the Asset Id of the video.v4+
browserTextDim.Browser used for the video view (Safari, Chrome, etc.).v2+
browser (viewer_application_name)TextDim.Deprecated - see browserv1
browser_versionVersionDim.Browser version (e.g. 66.0.3359.158).v2+
browser_version (viewer_application_version)VersionDim.Deprecated - see browser_version (viewer_application_version)v1
cdnTextDim.CDN delivering the video view, either determined by response header auto-detection or provided as video_cdn.v1+
cityTextDim.City of the viewer.v1+
continent_codeISO CodeDim.2-letter ISO code identifying the Continent of the viewer (e.g. NA, EU).v1+
countryISO CodeDim.2-letter Country Code.v2+
country (country_code)ISO CodeDim.Deprecated - see countryv1
country_nameTextDim.Country of the viewer.v1+
custom_1TextDim.Customer-defined metadata.v2+
custom_2TextDim.Customer-defined metadata.v2+
custom_3TextDim.Customer-defined metadata.v2+
custom_4TextDim.Customer-defined metadata.v2+
custom_5TextDim.Customer-defined metadata.v2+
custom_6TextDim.Customer-defined metadata.v5+
custom_7TextDim.Customer-defined metadata.v5+
custom_8TextDim.Customer-defined metadata.v5+
custom_9TextDim.Customer-defined metadata.v5+
custom_10TextDim.Customer-defined metadata.v5+
environment_idUnique IDDim.Mux Environment ID, linked with a specific environmentv4+
error_typeUnique IDDim.Mux-internal ID used to categorize errors.v2+
error_type (error_type_id)Unique IDDim.Deprecated - see error_typev1
exit_before_video_startBooleanMetricIdentifies when a viewer abandons the video because it is taking too long to load.v1+
experiment_nameTextDim.A/B Testing: use this field to separate views into different experiments.v1+
ispTextDim.Unusedv1+
latitudeDegreesDim.Latitude of the viewer, truncated to 1 decimal place.v1+
live_stream_idTextDim.If Mux Video is used, the Live Stream Id of the video.v4+
live_stream_latencyIntegerMetricLive Stream Latency measuring the average time from ingest to display for the view.v4+
longitudeDegreesDim.Longitude of the viewer, truncated to one decimal place.v1+
max_downscale_percentagePercentageMetricMaximum Downscale Percentage at any point in time during a video view.v2+
max_downscale_percentage (view_max_downscale_percentage)PercentageMetricDeprecated - see max_downscale_percentagev1
max_upscale_percentagePercentageMetricMaximum Upscale Percentage at any point in time during a video view.v2+
max_upscale_percentage (view_max_upscale_percentage)PercentageMetricDeprecated - see max_upscale_percentagev1
metroTextDim.Unusedv1+
mux_api_versionTextDim.Ignorev1+
mux_embed_versionDim.Dim.Internal version of Mux Core SDK. Ignorev1+
mux_viewer_idUnique IDDim.A Mux Internal ID representing the viewer who is watching the stream.v1+
operating_systemTextDim.Operating System (iOS, Windows, etc).v2+
operating_system (viewer_os_family)TextDim.Deprecated - see operating_systemv1
operating_system_versionVersionDim.Operating System version (e.g. 10.15).v2
operating_system_version (viewer_os_version)VersionDim.Deprecated - see operating_system_versionv1
page_load_timeMillisecondsMetricMeasures the time from the initial user request for a page to the time when the video player is first initializedv1+
page_typeTextDim.Provides the context of the page for more specific analysis. Values include watchpage or iframe.v1+
page_urlURLDim.Page URLv1+
platform_descriptionTextDim.Unusedv1+
playback_idTextDim.If Mux Video is used, the Playback Id of the video.v4+
playback_success_scoreDecimalDim.Playback Success Scorev2+
player_autoplayBooleanDim.Indicates whether the player autoplayed the video or notv1+
player_error_codeStringDim.An error code that represents a fatal error (one resulting in playback failure). Often an integer, but implementation-dependent.v1+
player_error_contextTextDim.Error instance-specific information such as stack trace or segment number.v5+
player_error_messageTextDim.Message sent by the player when an error has been fired up (associated with an error code)v1+
player_heightIntegerDim.Height of the player as displayed in page, in pixelsv1+
player_instance_idUnique IDDim.Identifies the instance of the Player class that is created when a video is initializedv1+
player_languageTextDim.Player's text languagev1+
player_load_timeMillisecondsMetricDeprecated - see player_startup_time)v1+
player_mux_plugin_nameTextDim.Mux Integration Plugin name (e.g. mux-player)v1+
player_mux_plugin_versionVersionDim.Mux Integration Plugin version (e.g. 2.2.0)v2+
player_nameTextDim.Identifies different configurations or types of players around your site or application (e.g. My Player)v1+
player_posterURLDim.The image shown as the pre-visualisation before playv1+
player_preloadBooleanDim.Specifies if the player was configured to load the video when the page loads.v1+
player_remote_playedBooleanDim.Specify from the SDK if the video is remote played to AirPlay or Chromecast.v2+
player_softwareTextDim.Player Software being used to play the Video (e.g. Video.js, JW Player, etc.)v1+
player_software_versionTextDim.Player Software Version (e.g. 2.45.5)v1+
player_source_domainTextDim.Video Source Domain (e.g. myvideostreams.com)v1+
player_source_durationMillisecondsDim.Video Source Durationv1+
player_source_heightIntegerDim.Height of the source video being sent to the player, in pixelsv1+
player_source_stream_typeTextDim.Unusedv1+
player_source_urlURLDim.Video Source URLv1+
player_source_widthIntegerDim.Width of the source video being as seen by the playerv1+
player_startup_timeMillisecondsMetricMeasures the time from when the player is first initialized in the page to when it is ready to receive further instructions.v1+
player_versionTextDim.As you make changes to your player you can compare how new versions of your player perform. Set in combination with player_name (e.g. 1.2.0)v1+
player_view_countIntegerDim.View Count - equal to 1 in Full Exports (1 line = 1 video view)v1+
player_widthIntegerDim.Width of the player as displayed in page, in pixelsv1+
property_idUnique IDDim.Mux Property ID, linked with a specific environment. Deprecated, please use environment_id.v1+
rebuffer_countIntegerMetricNumber of rebuffering events that happen during the video view.v2+
rebuffer_count (buffering_count)IntegerMetricDeprecated - see rebuffer_countv1
rebuffer_durationMillisecondsMetricAmount of time in milliseconds that viewers wait for rebuffering per video view.v2+
rebuffer_duration (buffering_duration)MillisecondsMetricDeprecated - see rebuffer_durationv1
rebuffer_frequencyEvents per millisecondMetricMeasures how often rebuffering events happen.v2+
rebuffer_frequency (buffering_rate)Events per millisecondMetricDeprecated - see rebuffer_frequencyv1
rebuffer_percentagePercentageMetricVolume of rebuffering that is occurring across the viewv1+
regionTextDim.Region of the viewerv1+
session_idUnique IDDim.Mux Session ID tracking a viewer's sessionv1+
smoothness_scoreDecimalScoreSmoothness Scorev2+
source_hostnameTextDim.Video Hostname (e.g. media.myvideos.com).v2+
source_hostname (player_source_host_name)TextDim.Deprecated - see source_hostnamev1
source_typeTextDim.Format of the source, as determined by the player. E.g. 'dash', 'application/x-mpegurl', 'video/mp4', etc.v2+
source_type (player_source_type)TextDim.Deprecated - see source_typev1
startup_time_scoreDecimalScoreStartup Time Scorev2+
stream_typeTextDim.Type of stream (e.g. 'live' or 'on-demand').v2+
stream_type (video_stream_type)TextDim.Deprecated - see stream_typev1
sub_property_idTextDim.Sub Property Idv2+
time_to_first_frameMillisecondsMetricDeprecated - see video_startup_timev1
used_fullscreenBooleanDim.Indicates whether the viewer used full screen to watch the video.v1+
video_content_typeTextDim.Content Type (e.g. 'short', 'movie', 'episode', 'clip', 'trailer', or 'event').v1+
video_durationMillisecondsDim.The length of the video supplied to Mux via custom metadatav1+
video_encoding_variantTextDim.An optional detail that allows you to compare different encoding settings.v1+
video_idUnique IDDim.Your internal ID for the videov1+
video_languageTextDim.The audio language of the video, assuming it's unchangeable after playing.v1+
video_producerTextDim.The producer of the video titlev1+
video_quality_scoreDecimalScoreVideo Quality Scorev2+
video_seriesTextDim.Series name (e.g. 'The Girls')v1+
video_startup_timeMillisecondsMetric(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_startup_failureBooleanMetricIdentifies when a viewer encounters an error before the first frame of the video begins playback.v7+
video_titleTextDim.Video Titlev1+
video_variant_idUnique IDDim.Your internal ID for a video variantv1+
video_variant_nameTextDim.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_percentagePercentageMetricDownscale Percentagev2+
view_drm_typeTextDim.The type of DRM used during playback (e.g. 'widevine' or 'playready').v5+
view_dropped_frame_countIntegerMetricThe number of frames that were dropped by the player during playbackv5+
view_endTimeDim.Date and Time at which the view ended, in UTC.v1+
view_has_adBooleanMetricIdentifies if an advertisement played or attempted to play during the video view.v6+
view_idUnique IDDim.Unique View Identifierv1+
view_max_playhead_positionMillisecondsDim.The furthest the video was played, indicated by the maximum time value of the playhead during the view.v3+
view_playing_timeMillisecondsMetricThe amount of time the video spent playing during the view; this value does not include time spent joining, rebuffering, or seeking.v3+
view_seek_countIntegerDim.The number of times that the viewer attempted to seek to a new location within the view.v1+
view_seek_durationMillisecondsDim.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_idUnique IDDim.An id that can be used to correlate the view with platform services upstream such as CDN or origin logs.v2+
view_startTimeDim.Date and Time at which the view started, in UTC.v1+
view_total_content_playback_timeMillisecondsDim.Internal metric used in calculating upscale and downscale percentages.v1+
view_total_downscalingMillisecondsDim.Internal number used to calculate Downscale Percentage Metric. Downscale Percentage = view_total_downscaling / view_total_content_playback_timev1+
view_total_upscalingMillisecondsDim.Internal number used to calculate Upscale Percentage Metric. Upscale Percentage = view_total_upscaling / view_total_content_playback_timev1+
view_upscaling_percentagePercentageMetricUpscale Percentagev2+
viewer_application_engineTextDim.Web Browser Engine (Gecko, WebKit, etc)v1+
viewer_connection_typeTextDim.The type of network connection used by the device, where available (e.g. mobile, wired, wireless)v2+
viewer_device_categoryTextDim.The type of device used (e.g. console, desktop, phone, tablet, TV)v1+
viewer_device_manufacturerTextDim.Device Brand (e.g. Apple, Microsoft)v1+
viewer_device_modelTextDim.Device Model (e.g. iPhone11,2)v4+
viewer_device_nameTextDim.Device Name (e.g. iPhone 12)v1+
viewer_experience_scoreDecimalScoreOverall Viewer Experience Scorev2+
viewer_os_architectureTextDim.No longer used. Ignore.v1+
viewer_user_agentTextDim.User Agent (e.g. Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0))v1+
viewer_user_idUnique IDDim.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_timeMillisecondsDim.Total Watch Time across the view (includes Startup Time, Playing time, potential rebuffering).v1+
watchedBooleanDim.Ignorev1+
weighted_average_bitratebits/secMetricWeighted Average Bitrate, expressed in bps.v2+

Ad Metrics and Dimensions

Mux API ValueUnitTypeDefinitionVersions
preroll_ad_asset_hostnameHostnameDim.Hostname of the Preroll Ad Asset.v1+
preroll_ad_tag_hostnameHostnameDim.Hostname of a Preroll Ad Tag.v1+
preroll_playedBooleanDim.Flag to identify video views for which a Preroll Ad has been successfully played.v1+
preroll_requestedBooleanDim.Flag to identify video views for which a Preroll Ad has been requested.v1+
requests_for_first_prerollIntegerMetricMeasures the number of ad requests that are made up to the point of preroll ad playback beginning.v1+
video_startup_preroll_load_timeMillisecondsMetricTotal amount of Video Startup Time that is spent loading the first preroll ad asset.v1+
video_startup_preroll_request_timeMillisecondsMetricTotal amount of Video Startup Time that is spent making preroll ad requests.v1+

Request-level Metrics

Mux API ValueUnitTypeDefinitionVersions
max_request_latencyMillisecondsMetricMaximum time to first byte for a media request.v2+
max_request_latency (view_max_request_latency)MillisecondsMetricDeprecated - see max_request_latencyv1
request_latencyMillisecondsMetricMeasures the average time to first byte for media requests.v2+
request_latency (view_average_request_latency)MillisecondsMetricDeprecated - see request_latencyv1
request_throughputbits/secMetricMeasures the average throughput, in bits per second, for all media requests that were completed.v2+
request_throughput (view_average_request_throughput)bits/secMetricDeprecated - see request_throughputv1

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.

The JSON format streaming export contains identical fields as the protobuf-encoded format.

Streaming Export versioning

Backward compatibility

The Streaming Export schema provided by Mux Data is backward compatible, meaning that each schema version guarantees that it will still work upon future upgrades. Customers do not need to worry about breaking changes.

When to upgrade the schema?

When Mux adds new fields into the Streaming Export, we will upgrade the schema version. Without taking any actions you will not be impacted by it: the fields that you used to get will keep working as normal, and the new fields introduced since your last upgrade will not be sent to you either. The benefit of designing it this way is that you will not be getting new fields without knowing.

For customers who want to get the new fields, read below to see the how-tos.

How to upgrade the schema?

If integrated with Google Pub/Sub

If your Google Pub/Sub topic is schematized, once a schema is associated with a topic, you can no longer change that schema. This means that customers using Google Pub/Sub for Streaming Export must take a couple of steps to move to a new topic that is associated with a new schema.

  • Create a new topic in Google Pub/Sub with upgraded schema
  • Point the Mux Data Streaming Export to that new topic
  • Go to Mux Dashboard → Settings → Streaming Export → Click Upgrade.

If your Google Pub/Sub topic is schemaless, which it must be if you want to use JSON, you do not need to create new topics or reconfigure your streaming export, but to get the new fields released from Mux, customer needs to do the 3rd step as mentioned above.

If integrated with Amazon Kinesis

  • If using protobuf message format, make sure you get the latest protobuf definition from Mux public repo. Subscribe to the mux-protobuf repository to receive updates.
  • Go to Mux Dashboard → Settings → Streaming Export → Click Upgrade button.

Was this page helpful?