Engagement

Operations related to engagement analytics for a VOD stream.

Fetch engagement analytics data for a VOD stream

(Available from version 1.11) This operation returns the engagement data for a specific VOD stream. Engagement data provides insight into how many plays your stream received and for how long.

If you don't send from and to query parameters, the last hour's worth of data is returned. See the trend field in the response for information about sample intervals.

If the time range between from and to query parameters is:

Less than 60 minutes, the cache time between responses is 10 seconds.
More than 60 minutes, the cache time between responses is 60 seconds.

Request

path Parameters

required

string

The unique alphanumeric string that identifies the VOD stream.

query Parameters

from	string <date-time> Use this parameter, along with to, to return historic viewer data. The start of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried is rounded to the nearest second. If you set the from query parameter without setting the to query parameter, the data returned will reflect 30 days starting at the from date, or data up to to the current day, whichever is shorter. Example: 2023-01-14T10:31:54.486Z
to	string <date-time> Use this parameter, along with from, to return historic viewer data. The end of the range of time you want to view. Specify YYYY-DD-MMT HH:MM:SSZ where HH is a 24-hour clock in UTC. The range queried is rounded to the nearest second. If you set the to query parameter without setting the from query parameter, the data returned will be from the past 30 days. Example: 2023-02-14T10:31:54.486Z
include	string Specify the data you want returned in the response. The only valid value for this endpoint is trend. Valid values are: trend Example: trend

Responses

200

Success

Response Schema: application/json

object (vod_stream)

id	string <int32> The unique alphanumeric string that identifies the VOD stream.
play_rate	integer <int32> The ratio between displays and plays. For example, 100 displays and 20 plays will result in 0.20 which means that 20% of the displays resulted in a play.
completion_rate	integer The ratio of viewers that watched the last segment of the asset. It is represented in a decimal value.
duration_ms	integer The length of the stream in milliseconds.
avg_seconds_watched	integer The average number of seconds the viewers viewed the stream.
avg_percentage_watched	integer The average time watched represented as a percentage.
total_seconds_watched	integer The total number of seconds the stream was viewed.
	object (Array of viewer trends) An array of viewer trend data for an asset in the given time period. Note: Data from the most recent hour data might not be included in the result of a time range that extends beyond the most recent 3 days. Default: Last hour
	object The time frame represented in the response.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

get/analytics/engagement/vod_streams/{id}

Request samples

Shell
JavaScript
Java
Python

// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v2.0/analytics/popularity/vod_streams/tvctq36g?from=2023-04-14T10:31:54.486Z&to=2023-07-13T10:31:54.486Z&include=trend"

Response samples

application/json

{"vod_stream": {"id": "tvctq36g",
"play_rate": 0.2,
"completion_rate": 0.42,
"duration_ms": 9761000,
"avg_seconds_watched": 302,
"avg_percentage_watched": 67,
"total_seconds_watched": 77699,
"trend": [{"percent": 1,
"viewers": 7
},
{"percent": 2,
"viewers": 7
},
{"percent": 3,
"viewers": 7
},
{"percent": 4,
"viewers": 7
},
{"percent": 5,
"viewers": 10
},
{"percent": 6,
"viewers": 7
},
{"percent": 7,
"viewers": 7
},
{"percent": 8,
"viewers": 25
},
{"percent": 9,
"viewers": 25
},
{"percent": 10,
"viewers": 25
},
{"percent": 11,
"viewers": 7
},
{"spercent": 12,
"viewers": 7
},
{"percent": 13,
"viewers": 7
}
]
},
"limits": {"from": "2024-03-14T10:31:54.000Z",
"to": "2024-04-13T10:31:54.000Z"
}
}