Metrics
Here are the complete reference details for all metrics for the v3 Analytics Reporting API.
Metrics are specified with the metrics= query string parameter. Multiple values must be comma-separated with no spaces.
- 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.
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 milliseconds. (In the UI, this value is converted to HH:MM:SS format.) | |
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. |
|
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.
|
|
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.
|
|
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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: 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. | Performance |
digg | Number of times the "Digg" button has been pressed. | Performance |
emails_sent | Number of times the "share via email" button is pressed. | Performance |
Number of times the Facebook "Like" button has been pressed. | Performance | |
Number times the Twitter "tweet" button is pressed. | Performance | |
urls_copied | Number of times the "Copy URL" button has been pressed. | 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 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 returned if a query contains
time_segment=hour or
time_segment=15min.
|
Performance |