Analytics API FAQ

Below are some frequently asked questions about the Analytics API. For answers to some of the common questions about the Video Cloud Studio Analytics module, see FAQ: Analytics Module. Have a question that you do not see here? Let us know!

Date ranges

How do I return data for all time in a Report?
Set from=alltime in the request. You can also set to=now, but this isn't necessary, since now is the default value. Note: alltime does not work for a Rollup - instead you will need to set from to a date far enough in the past.
How do I get data for a specific day?
Set both the from and to values to that date. For example: from=2013-05-12&to=2013-05-12.

Data granularity

What is the granularity of recent Analytics data?
For the most recent 32 days (including the current day), the Analytics API reports an hour granularity, because it saves values into hourly buckets. However, the current hour is still being filled, so this can give the API the appearance of having more granularity than an hour when you ask for data that falls in the current hour.

For example:

  1. If you ask for data from 3 hours ago for 9:15 and 9:20 you will get the same value if they fall in the same hour bucket.
  2. If you ask for data from 10 minutes go, and then wait 5 minutes and ask again you may get a different value even if it is in the same bucket, because that bucket is still being updated.
What is the refresh interval for the analytics data?
The /data endpoint is currently cached for 5 minutes between queries, so for lists of videos with traffic in the last hour, 5 minute intervals is the smallest delay that will give you a delta to work from.
What is the granularity of historical Analytics data?
For dates earlier than the last 32 days, the Analytics API reports full day values. This means that if your requested from=1368334306919&to=1378446336919 (from Sun, 12 May 2013 04:51:46 GMT to Fri, 06 Sep 2013 05:45:36 GMT), you would get the same results that you would if you had requested from=2013-05-12&to=2013-09-06

Items and fields

What is the best way to tell how many stream starts there were in a period for one or more videos?
Just look at the video_view metric - this will always be equal to the stream starts. You can see this metric in all reports, and the summary will show you stream starts for all videos in the date range queried. To see stream starts for all videos in your account, you would just run this request:{account_ids}&dimensions=video&limit=all&offset=0&fields=all
What data fields are returned for items by default?
By default, video_view and the field corresponding to the dimension you are reporting on are returned.
How do I return all items in a Report?
Set the limit parameter for the Report equal to all.
What data fields are returned for items by default?
By default, only video_view and the field corresponding to the dimension requested (e.g. destination_domain) are returned. To get additional fields, set fields=all to return all fields, or fields=field_name1,field_name2 to return selected fields.
What does it mean if a field value is null?
A null value for a data field indicates that the data requested has not been processed. The most likely reasons are that:
  • The data you requested is very recent and has not been processed yet
  • The data you requested is very old and has not yet been imported into the current analytics system
I changed the name of one of my videos - why do I see the old name in Analytics data?
The new name will be recorded for any new analytics events, but we do not change the name in historical data - the video name returned will be the name it had at the time it was viewed.
Why don't I always see integers for engagement values?
It is possible for engagement numbers to return with decimal points. The reason is because engagement is normalized which means that it's a ratio of "video_percent_viewed * (video_engagement_25 / video_engagement_sum)" so based on the time range selected for the query you may see floating point numbers in cases where they don’t divide exactly.
How do I filter results by player?
Why does bytes_delivered sometimes return a null value?
This will happen if the bytes_delivered data is not available for the time period you have requested. The bytes_delivered metric has 2-3 days of latency, so if, for example, you asked for this data over the last 30 days (including today), bytes_delivered would be null since the requested range includes days that do not yet have this data. To avoid this when requesting bytes_delivered data, make sure that the range requested is outside of the latency period.


Why do I see 0 GB when I look at bandwidth used by a player?
In the past Brightcove has reported bandwidth by player, and so for customers that wanted to break things down by player they could use these metrics as a means of allocating bandwidth costs. However, as we move toward more manifest-driven delivery (HLS today and DASH in the future), the nature of segmented video will make tracking bandwidth by player inaccurate. Therefore, we will be deprecating the bandwidth by player dimension in the Utilization report. So going forward we recommend using seconds viewed by player in the Performance report to allocate costs by player.


Can I exclude employee views from analytics reports?
There is no easy way to do this, and for high-traffic videos, employee views are probably such a small percentage that their effect on analytics is negligible. However, for low traffic videos where you think it's important to do this, the simplest solution is to duplicate your production player(s) and have employees test/view videos on the copies. You can then use filters to create reports on your production player(s) only, using either the Custom Reports feature in the Analytics module or the Analytics API.