Metrics

Here are the complete reference details for all metrics for the v3 Analytics Reporting API.

Note: All metrics, except for player_loads, are associated with the asset pcode. The player_loads metric is associated with the player pcode.

Metrics are specified with the metrics= query string parameter. Multiple values must be comma-separated with no spaces.

Note: You can retrieve the entire set of metrics by not including metrics in your query.
Warning: If you don't specify metrics for the url dimension, an error message will be returned. Supported metrics for the url dimension include:
  • displays
  • plays_requested
  • video_starts
  • time_watched
  • player_loads
  • replays
  • uniq_plays_requested
  • uniq_displays
  • uniq_video_starts
  • playthrough_25
  • playthrough_50
  • playthrough_75
  • playthrough_100

To retrieve a specific metric, specify it as in the following examples:

  • metrics=plays_requested
  • metrics=uniq_plays_requested
  • metrics=displays,uniq_displays

General Syntax of Reporting GET

The base syntax of the route and query string is as follows. For ease of reading, the single-line request has been split across several lines.

[GET] /v3/analytics/reports/?
            report_type=type
            &dimensions=dimensions
            &metrics=metrics
            &filters=filter_type=='filter_value'
            &start_date=date
            &end_date=date
            &other_parms
            &api_key=your_api_key
         
  • The required query string parameters (shown in bold) are report_type, start_date, and api_key.
  • If no dimensions are specified, total values across all dimension are returned.
  • For time ranges up to 1 month you can query by up to 3 dimensions at a time with unlimited rows of data. For time ranges greater than one month you can query by up to 2 dimensions at a time with up to 10,000 rows of data.
  • If no metrics are specified, all metrics are returned.
Note: You may pass the API key either as a query parameter or via the header X-API-KEY.
Note: At this time, the only valid value for report_type is performance.
Note: You can only use 1 dimension (url) for url queries.

General Syntax of Reporting Long Queries POST

For queries with query parameters that would exceed the HTTP GET specification limit of 230 characters , please use a POST request. Some browsers and http clients may support more than 230 characters, but we will not provide official support for queries that violate the HTTP GET specification. For POST requests, pass a JSON object in the request body instead of the query string parameters.

[POST] /v3/analytics/reports

{
    "report_type":"type",
    "dimensions":"dimensions",
    "metrics":"metrics",
    "filters":"(filter_type==\"filter_value\")",
    "start_date":"date",
    "end_date":"date",
    "other_parms":"other_param_value",
    "api_key":"your_api_key"
}
         

Unique Users

You may want to measure the number of unique users. To measure unique users, use the uniq_plays_requested metric described below. The Ooyala mobile SDKs generate and store a random unique ID which is application-specific. In other environments, a unique user is identified by local storage or cookie. If a user clears their browser cache, that user/device's ID will get regenerated next time they watch video. The generated IDs are completely random and don't include any user-identifiable information. When such information is not available for a user, a new unique identifier will be created for that user. We de-duplicate when calculating the number of unique users over time. For example, day 1 has users A, B, C; day 2 has users B, E., then when you pick date range = day 1 and day 2, then total unique users = 4 (A, B, C, E), Daily Avg. Unique Users = (3+2) / 2 = 3 (2.5 is converted to the closed integer).

Video and Engagement-Related Metrics

Metric Name Meaning Related Event, UI Label
plays_requested The number of times that the "Play" button is triggered either manually or automatically for any content (including video and ad content). This metric does not include the replay event.
Note: We have improved our calculation of this metric. You may see the number of plays requested from your HTML5 and SDK players increase after 11/11/2014 due to this implementation.
Plays Requested on Business Intelligence page
displays The number of times that the particular video content is loaded and displayed within the player before it gets played (displays are related to each individual asset). Each time an embed code is changed this event gets triggered. Displays on Business Intelligence page
replays Number of times the replay button is clicked.  
video_starts Number of times the actual non-ad video content begins playback. Thus, not fired until the completion of pre-roll ads and actual asset playback has begun. If a user clicks on the “Play” button, a pre-roll ad starts playing, and the user drops off before the actual video content starts playing, this event won’t be triggered.
Note: We have improved our calculation of this metric. You may see the number of video starts from your HTML5 and SDK players decrease after 11/11/2014 due to this implementation.
Video Starts on Business Intelligence page
time_watched Amount of time the user spent playing back the video asset, in HH:MM:SS format. We have added a smart format for values >1000h (For example, "1234:56:57" gets converted to "1.2k").  
playthrough_25 Number of video plays for the selected assets that reached the state of 25% completion of the video asset. No matter how many times the user rewinds within the same view/play session, once the "state" is reached it won't be marked/counted again. For example, within the same video viewing session (i.e. a user didn't refresh the page or reload the player), if a user rewinds and watches through the 25% quartile multiple times, Playthrough 25% will only count once.

Applies only to video-on-demand (VOD), not live streams.

 
playthrough_50 Number of video plays for the selected assets that reached the state of 50% completion of the video asset. No matter how many times the user rewinds within the same view/play session, once the "state" is reached it won't be marked/counted again. For example, within the same video viewing session (i.e. a user didn't refresh the page or reload the player), if a user rewinds and watches through the 50% quartile multiple times, Playthrough 50% will only count once.

Applies only to video-on-demand (VOD), not live streams.

 
playthrough_75 Number of video plays for the selected assets that reached the state of 75% completion of the video asset. No matter how many times the user rewinds within the same view/play session, once the "state" is reached it won't be marked/counted again. For example, within the same video viewing session (i.e. a user didn't refresh the page or reload the player), if a user rewinds and watches through the 75% quartile multiple times, Playthrough 75% will only count once

Applies only to video-on-demand (VOD), not live streams.

 
playthrough_100 Number of video plays for the selected assets that reached the state of 100% completion of the video asset. No matter how many times the user rewinds within the same view/play session, once the "state" is reached it won't be marked/counted again. For example, within the same video viewing session (i.e. a user didn't refresh the page or reload the player), if a user rewinds and watches through the 100% quartile multiple times, Playthrough 100% will only count once.

Applies only to video-on-demand (VOD), not live streams.

 
avg_time_watched_per_video Average video viewing time, calculated as sum(time watched)/video_starts, converted to HH:MM:SS format.
Note: We have improved our calculation of video starts. You may see avg_time_watched_per_video increase after 11/11/2014 due to this implementation.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
 
play_conversion_rate Ratio of plays requested events to displays events.
Note: We have improved our calculation of plays requested. You may see the play_conversion_rate metric from your HTML5 and SDK players increase after 11/11/2014 due to this implementation.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
 
video_conversion_rate Ratio of video starts events to plays requested events.
Note: We have improved our calculation of video starts and plays requested. You may see the number of video starts from your HTML5 and SDK players change after 11/11/2014 due to this implementation.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
 
player_loads Triggered each time the player loads on the page. The player_loads metric is associated with the pcode for the player.  

Discovery Insights Metrics

Metric Name Meaning Used in Report Type
end_screen_ctr The CTR of the Discovery end screen, including auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
end_screen_ctr_excluding_autoplays The CTR of the Discovery end screen, excluding auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
end_screen_impressions The number of impressions of the Discovery end screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
pause_screen_ctr The CTR of the Discovery pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
pause_screen_impressions The number of impressions of the Discovery pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
aggregate_ctr The CTR covering impressions and clicks of both the Discovery end screen and pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
lift_percent_end_screen The lift from the Discovery end screen alone, including auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
lift_percent_end_screen_excluding_autoplays The lift from the Discovery end screen alone, excluding auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
lift_percent_pause_screen The lift from the Discovery pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
aggregate_lift_percent Total lift covering plays from the Discovery end screen and pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
added_view_time_hours The total added view time in hours attributed to Discovery plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
time_lift_percent_end_screen The time lift from the Discovery end screen alone, including auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
time_lift_percent_end_screen_excluding_autoplays The time lift from the Discovery end screen alone, excluding auto-plays.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
time_lift_percent_pause_screen The time lift from the Discovery pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
aggregate_time_lift_percent Total time lift covering plays from the Discovery end screen and pause screen.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
discovery_plays

Discovery Plays measure how many times a video was played after a recommendation by Discovery.

Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
discovery_leads

Discovery Leads measure the number of times different Discovery-recommended videos got played as a result of watching the original video. For example, the video asset "The Big Game" has a Discovery end screen at the end of the video. Discovery Leads measures the number of times a video shown on the Discovery end screen for "The Big Game" get played. For additional details on what value you can derive from Discovery Plays and Leads data, see Deriving Value From Discovery Insights.

Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance

Other Metrics and Their Related Reports

Metric Name Meaning Used in Report Type
uniq_plays_requested Number of unique users that trigger the "play" button (manually or automatically) for any content (see plays_requested).

Note: uniq_plays_requested is a measure of Unique Users (uniq_users).

Note: We have improved our calculation of this metric. You may see the number of plays requested from your HTML5 and SDK players increase after 11/11/2014 due to this implementation.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
uniq_displays Number of unique users that see the video loaded and displayed within the player before it gets played (displays are related to each individual asset). Each time an embed code is changed the display event gets triggered (see displays).
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
uniq_video_starts Number of unique users that see playback of actual non-ad video content (see video_starts).
Note: We have improved our calculation of this metric. You may see the number of video starts from your HTML5 and SDK players decrease after 11/11/2014 due to this implementation.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
embeds_copied Number of times the embed code has been copied.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
digg Number of times the "Digg" button has been pressed.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
emails_sent Number of times the "share via email" button is pressed.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
facebook Number of times the Facebook "Like" button has been pressed.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
twitter Number times the Twitter "tweet" button is pressed.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
urls_copied Number of times the "Copy URL" button has been pressed.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Performance
segment_watched The number of times each segment of a piece of video content is watched. 1 segment is defined as 2.5% of video length. Please note if a user rewinds and watches the same segment N times, Segments Watched for that segment will count as N times.

Applies only to video-on-demand (VOD), not live streams.

Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance
percentage_watched Measures the percentage of a video (in its entirety) that ever got watched in increments of 2.5%. This metric will not increase if a user rewinds and re-watches a segment in the same video session.
Note: This metric is not available for the url dimension. If you specify this metric with a url query, an error message will be returned.
Note: This metric is not returned if a query contains time_segment=hour or time_segment=15min.
Performance

Was this article helpful?