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 - average 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

Response

    Response will appear here when you test a request

Dimension: video