Product Updates | Contact Support | System Status
Page Contents

    Dimension: video

    In this topic, you will learn about the Analytics API video dimension. The video dimension provides analytics by video. NOTE: if you wish to include any "video." fields (such as video.name) in the response, your client credentials must include the CMS: Video read permission. Also note that while you cannot return video.custom_fields, you can return video.custom_fields.{field_name}.

    URL parameters

    Analytics API reports support the following URL parameters.

    URL Parameters
    Parameter Description Required Values Default
    account The accounts you want to report on yes one or more account ids as a comma-delimited list none
    dimensions The dimension(s) to report on yes one or more dimensions as a comma-delimited list (some combinations are not valid) none
    where Used to specify filters for reports no {dimension}=={value} - one or more as a semi-colon-delimited list none
    limit Number of items to return no positive integer 10
    offset Number of items to skip no positive integer 0
    sort Field to sort items on no a valid field for the request video_view
    fields Fields to return no varies according to the dimension you are reporting on video_view
    format Format to return results in no json | csv | xlxs json
    reconciled If included, will limit results to either historical or realtime data no true | false true
    from The beginning of the date range for the request no An ISO 8601 date (YYYY-MM-DD), epoch time in milliseconds, the string alltime, or relative date (-1m); only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false. 30 days prior to now
    to The end of the date range for the request no An ISO 8601 date (YYYY-MM-DD), epoch time in milliseconds, the string now, or relative data (+7d); only dates within the past 32 days are allowed for engagement endpoints or if reconciled=false. now

    Fields available

    The following fields can be returned for the dimension.

    • ad_mode_begin - the number of times the player entered ad mode
    • ad_mode_complete - the number of times the player completed ad mode
    • bytes_delivered - total bytes delivered to client machines for the player and associated media
    • engagement_score - the engagement score for a video
    • play_request - total number of times video playback was requested
    • play_rate - the average play rate (video views divided by impressions) for a video
    • video - the video id
    • video_duration - the video duration (if reported)
    • video_engagement_1 - the number of views at the 1 percent point of the video
    • video_engagement_100 - the total number of views at the 100 percent point of video duration
    • video_engagement_25 - the total number of views at the 25 percent point of video duration
    • video_engagement_50 - the total number of views at the 50 percent point of video duration
    • video_engagement_75 - the total number of views at the 75 percent point of video duration<
    • video_impression - the total number of times the video was loaded into players
    • video_name - the name of video at the time of the most recent impression in the time-frame
    • video_percent_viewed - the sum of percentage of the video viewed for all video views. For example if there were two views in the period, and the percentage viewed in one view was 78%, and 59% in the other, the video_percent_viewed returned would be 137.
    • video_seconds_viewed - total seconds viewed for each video view
    • video_view - the number of times video playback began
    • video.reference_id - the video's reference id
    • video.name - the video's current name
    • video.description - the video's current description
    • video.complete - whether video processing is complete
    • video.created_at - the date/time when the video was created
    • video.duration - the video's current duration
    • video.economics - whether the video is enabled for ads
    • video.long_description - the video's long description
    • video.state - whether the video is currently ACTIVE or INACTIVE
    • video.tags - the video's tags
    • video.updated_at - date/time when the video was last modified
    • video.custom_fields.{field_name} - value for the video's custom field named {field_name}
    • video_download_request - number of download requests for a video enabled for offline playback
    • video_download_complete - number of times a video enabled for offline playback was completely downloaded
    • video_download_cancellation - number of times download of a video enabled for offline playback was cancelled (including times the page was closed before download completed)
    • video_download_error - number of times download of a video enabled for offline playback failed due to an error

    Filter values

    Used as a filter, a dimension allows you to narrow the results.

    Filter values: video ids as a comma-delimited list or video.q=={video field}:{value}

    Combining dimensions

    To see what dimensions this on can be combined with, and what fields are available for the combination, see Dimension and Fields.

    Request Examples

    Dimension request

        https://analytics.api.brightcove.com/v1/data?accounts=1752604059001&dimensions=video

    Filter request

        https://analytics.api.brightcove.com/v1/data?accounts=1752604059001&dimensions=video&where=video==4093643993001,1754276206001
    Sample Response 
    {
	"item_count": 123,
	"items": [
		{
			"video": "2180741085001",
			"video_view": 1
		},
		{
			"video": "4446941108001",
			"video_view": 1
		},
		{
			"video": "2535301903001",
			"video_view": 1
		},
		{
			"video": "5323136098001",
			"video_view": 1
		},
		{
			"video": "1732474228567874935",
			"video_view": 1
		},
		{
			"video": "1723783757463121178",
			"video_view": 1
		},
		{
			"video": "4454620114001",
			"video_view": 1
		},
		{
			"video": "5271819050001",
			"video_view": 1
		},
		{
			"video": "2026627035001",
			"video_view": 1
		},
		{
			"video": "4446941103001",
			"video_view": 2
		}
	],
	"summary": {
		"video_view": 45136
	}
}
    Page last updated on 30 May 2022