Skip to main content

Export Viewing Report

Watch time is a crucial metric for any streaming service. It measures the total duration viewers have spent watching your content within a specific date range. This includes VODs, live events, and associated live-to-VOD playbacks. Understanding watch time can help you assess viewer engagement and make informed decisions about your content strategy.

About the Watch Time Report​

A watch time report provides detailed information about the following:

  • Content Information: This includes the content's title, content ID, streaming type, and when the content was created.
  • Customer ID: These are custom-defined user IDs that help you identify the playbacks of your users.
  • Watch Time (sec.): This is the amount of time viewers spend watching the content, broken down by different content, type, and customer IDs.

Here is an example of a watch time report (20230703.csv) for the VOD viewing history that occurred on July 3, 2023, from 00:00:00 to 23:59:59: Watch Time Example

Generate the Watch Time Report​

To generate a watch time report, you can use the following API:

GET /bv/analytics/v1/reports/watch-time

This API accepts two query parameters:

  • streaming_type: This specifies the content type you want to generate the report. It can be either REPORT_STREAMING_TYPE_LIVE for live events and associated Live-to-VOD or REPORT_STREAMING_TYPE_VOD for VODs.
  • time: This specifies the date for the report in the ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ). The report will include the total watch time for all views initiated from 00:00:00 to 23:59:59 on the specified date.

Here's an example of a request in cURL:

curl --request GET
  --url 'https://api.one-qa.kkstream.io/bv/analytics/v1/reports/watch-time?time=2023-07-03T00%3A00%3A00&streaming\_type=REPORT\_STREAMING\_TYPE\_VOD'
  --header 'Accept: application/json'
  --header 'authorization: Bearer <your-api-token>'
  --header 'x-bv-org-id: <your-organization-id>'

A successful response will contain a URL for the watch time report:

{
  "url": "string"
}

Now you can access your report by navigating to this URL.

Noted:

  1. If the report is unavailable (1-2 days) or the specified date has no viewing history, the API will respond with a 404 error.
  2. The URL will expire after one hour. If it expires, please use this API again to fetch a new one.