Watch Time 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:

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 '' \
  --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.


  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.