Skip to content
Stream
Visit Stream on GitHub
Set theme to dark (⇧+D)

Fetching per-video analytics

Cloudflare measures the following metrics for every video play:

MetricNameExampleUnit
totalTimeViewedMsTotal time viewed1000Time in milliseconds
totalImpressionsTotal views50Impressions

You can slice and dice your analytics by the following dimensions:

DimensionNameExample
videoIdVideo ID40d67c87c6cd4b889a4fd57805225e85

You can also filter the data using the following operators:

OperatorNameURL Encoded
==Equals%3D%3D
!=Does not equals!%3D
>Greater Than%3E
<Less Than%3C
>=Greater than or equal to%3E%3D
<=Less than or equal to%3C%3D

Filters can be combined using OR and AND boolean logic. AND takes precedence over OR in all the expressions. The OR operator is defined using a comma (,) or OR keyword surrounded by whitespace. The AND operator is defined using a semicolon (;) or AND keyword surrounded by whitespace.

Analytics request structure

curl https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/stream/analytics/views?metrics={metrics}&dimensions={dimensions}&filters=videoId==$VIDEOID&since=2018-01-01T16:57:00Z&sort={sort}&until={to-timestamp}&limit={limit}
  • metrics is one or more metrics (such as count) to compute
  • dimensions can be used to break down the data by given attributes
  • filters used to filter rows by one or more dimensions (see Filters section below)
  • sort is the sort order for the result set; sort fields must be included in METRICS or DIMENSIONS
  • to-timestamp is that end of time interval to query, defaults to current time
  • from-timestamp is that start of time interval to query, defaults to TO_TS - 6 hours
  • step is used to select time series resolution when using endpoint:
  • auto or omitted - selects time step most appropriate to time interval. Other time
    • year
    • quarter
    • month
    • week
    • day
    • hour

Example analytics query

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT/stream/analytics/views?metrics=totalImpressions,totalTimeViewedMs&dimensions=videoId&filters=videoId==$VIDEOID&since=2018-01-01T16:57:00Z" \
-H "X-Auth-Email: $EMAIL" \
-H "X-Auth-Key: $APIKEY" \
-H "Content-Type: application/json"

Example analytics response

{
"result": {
"rows": 1,
"data": [
{
"dimensions": [
""
],
"metrics": [
7,
37663
]
}
],
"data_lag": 0,
"min": {
"totalImpressions": 7,
"totalTimeViewedMs": 37663
},
"max": {
"totalImpressions": 7,
"totalTimeViewedMs": 37663
},
"totals": {},
"query": {
"dimensions": [
"videoId"
],
"metrics": [
"totalImpressions",
"totalTimeViewedMs"
],
"filters": "videoId==$VIDEOID",
"since": "2018-10-10T13:02:00Z",
"until": "2018-11-27T20:10:00Z",
"limit": 10000
}
},
"success": true,
"errors": [],
"messages": []
}
  • Analytics data is found in .data.metrics. We are reserving fields such as min and max for use in the future.
  • totalImpressions is the number of views on the video
  • totalTimedViewMs is the amount of time viewed in milliseconds
  • In this example, there are 7 totalImpressions and 37663 totalTimeViewedMs
"data": [
{
"dimensions": [
""
],
"metrics": [
7,
37663
]
}
],