Analytics
Retrieve aggregated metrics
Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time.
/data/metrics/{metric}/{aggregation} from string Use this query parameter to define the starting date-time of the period you want analytics for.
- If you do not set a value for
from, the default assigned value is 1 day ago, based on thetoparameter. - The maximum value is 30 days ago.
- The value you provide should follow the ATOM date-time format:
2024-02-05T00:00:00+01:00 - The API ignores this parameter when you call
/data/metrics/play/total.
- Format
- date-time
- Example
- "2024-02-05T00:00:00+01:00"
to string Use this query parameter to define the ending date-time of the period you want analytics for.
- If you do not set a value for
to, the default assigned value isnow. - The API ignores this parameter when you call
/data/metrics/play/total. - The value for
tois a non-inclusive value: the API returns data before the date-time that you set.
- Format
- date-time
- Example
- "2024-02-06T00:00:00+01:00"
filterBy string Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.
- If you do not set a value for
filterBy, the API returns the full dataset for your project. - The API only accepts the
mediaIdandmediaTypefilters when you call/data/metrics/play/total.
These are the available breakdown dimensions:
mediaId: Returns analytics based on the unique identifiers of a video or a live stream.mediaType: Returns analytics based on the type of content. Possible values:videoandlive-stream.continent: Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. Possible values are:AS,AF,NA,SA,AN,EU,AZ.country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.deviceType: Returns analytics based on the type of device used by the viewers. Possible response values are:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values includechrome,firefox,edge,opera.
- Example
- "filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox"
apiKey
metric string required
Use this path parameter to select a metric that you want analytics for.
playis the number of times your content has been played. You can use the aggregationscount,rate, andtotalwith theplaymetric.startis the number of times playback was started. You can use the aggregationcountwith this metric.endis the number of times playback has ended with the content watch until the end. You can use the aggregationcountwith this metric.impressionis the number of times your content has been loaded and was ready for playback. You can use the aggregationcountwith this metric.impression-timeis the time in milliseconds that your content was loading for until the first video frame is displayed. You can use the aggregationsaverageandsumwith this metric.watch-timeis the cumulative time in seconds that the user has spent watching your content. You can use the aggregationsaverageandsumwith this metric.
- Enum
-
- play
- start
- end
- impression
- impression-time
- watch-time
aggregation string required
Use this path parameter to define a way of collecting data for the metric that you want analytics for.
countreturns the overall number of events for theplaymetric.ratereturns the ratio that calculates the number of plays your content receives divided by its impressions. This aggregation can be used only with theplaymetric.totalcalculates the total number of events for theplaymetric.averagecalculates an average value for the selected metric.sumadds up the total value of the select metric.
- Enum
-
- count
- rate
- total
- average
- sum
Responses
Success
{
"context": {
"metric": "impression",
"aggregation": "count",
"timeframe": {
"from": "2024-05-28T11:15:07+00:00",
"to": "2024-05-29T11:15:07+00:00"
}
},
"data": 346.5
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Unrecognized request URL
{
"type": "https://docs.api.video/reference/unrecognized-request-url",
"title": "Unrecognized request URL.",
"status": 404
}Too Many Requests
{
"type": "https://docs.api.video/reference/too-many-requests",
"title": "Too many requests.",
"status": 429
}Bad request error
{
"type": "https://docs.api.video/reference/invalid-attribute",
"title": "An attribute is invalid.",
"status": 400,
"detail": "This value must be of type string.",
"name": "metric"
}This error occurs when a parameter you provided does not exist, or isn't correct for this endpoint, has an invalid value.
{
"type": "https://docs.api.video/reference/request-invalid-query-parameter",
"title": "A query parameter is invalid.",
"status": 400,
"detail": "This field was not expected.",
"name": "from:2024-05-20T09:15:05+02:00"
}This error occurs when a query parameter you provided does not exist, isn't correct for this endpoint, or has an invalid value.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
detail string A solution for the error.
name string The name of the parameter that caused the error.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
context object (context) required
metric string Returns the metric you selected.
- Enum
-
- play
- start
- end
- impression
- impression-time
- watch-time
- Example
- "impression"
aggregation string Returns the aggregation you selected.
- Enum
-
- count
- rate
- total
- average
- sum
- Example
- "count"
timeframe object (timeframe) Returns the starting and ending date-times of the period you want analytics for.
from string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-28T11:15:07+00:00"
to string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-29T11:15:07+00:00"
data number required
- Example
- "356.2"
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
Retrieve metrics in a breakdown of dimensions
Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type.
/data/buckets/{metric}/{breakdown} from string Use this query parameter to define the starting date-time of the period you want analytics for.
- If you do not set a value for
from, the default assigned value is 1 day ago, based on thetoparameter. - The maximum value is 30 days ago.
- The value you provide should follow the ATOM date-time format:
2024-02-05T00:00:00+01:00
- Format
- date-time
- Example
- "2024-02-05T00:00:00+01:00"
to string Use this query parameter to define the ending date-time of the period you want analytics for.
- If you do not set a value for
to, the default assigned value isnow. - The value for
tois a non-inclusive value: the API returns data before the date-time that you set.
- Format
- date-time
- Example
- "2024-02-06T00:00:00+01:00"
filterBy string Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics. You must use camelCase for query parameters.
- If you do not set a value for
filterBy, the API returns the full dataset for your project.
These are the available breakdown dimensions:
mediaId: Returns analytics based on the unique identifiers of a video or a live stream.mediaType: Returns analytics based on the type of content. Possible values:videoandlive-stream.continent: Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. Possible values are:AS,AF,NA,SA,AN,EU,AZ.country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.deviceType: Returns analytics based on the type of device used by the viewers. Possible response values are:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values includechrome,firefox,edge,opera.
- Example
- "filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox"
apiKey
metric string required
Use this path parameter to select a metric that you want analytics for.
playis the number of times your content has been played.play-rateis the ratio that calculates the number of plays your content receives divided by its impressions.play-totalis the total number of times a specific content has been played. You can only use themedia-idbreakdown with this metric.startis the number of times playback was started.endis the number of times playback has ended with the content watch until the end.impressionis the number of times your content has been loaded and was ready for playback.
- Enum
-
- play
- play-rate
- play-total
- start
- end
- impression
breakdown string required
Use this path parameter to define a dimension for segmenting analytics data. You must use kebab-case for path parameters.
These are the available dimensions:
media-id: Returns analytics based on the unique identifiers of a video or a live stream.media-type: Returns analytics based on the type of content. Possible values:videoandlive-stream.continent: Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. Possible values are:AS,AF,NA,SA,AN,EU,AZ.country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.device-type: Returns analytics based on the type of device used by the viewers. Possible response values are:computer,phone,tablet,tv,console,wearable,unknown.operating-system: Returns analytics based on the operating system used by the viewers. Response values includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values includechrome,firefox,edge,opera.
- Enum
-
- media-id
- media-type
- continent
- country
- device-type
- operating-system
- browser
Responses
Success
{
"context": {
"metric": "play",
"breakdown": "country",
"timeframe": {
"from": "2024-04-28T07:15:05+00:00",
"to": "2024-05-29T11:25:37+00:00"
}
},
"data": [
{
"metricValue": 7,
"dimensionValue": "FR"
}
],
"pagination": {
"currentPage": 1,
"currentPageItems": 1,
"pageSize": 25,
"pagesTotal": 1,
"itemsTotal": 1,
"links": [
{
"rel": "self",
"uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00¤tPage=1&pageSize=25"
},
{
"rel": "first",
"uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00¤tPage=1&pageSize=25"
},
{
"rel": "last",
"uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00¤tPage=1&pageSize=25"
}
]
}
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Unrecognized request URL
{
"type": "https://docs.api.video/reference/unrecognized-request-url",
"title": "Unrecognized request URL.",
"status": 404
}Too Many Requests
{
"type": "https://docs.api.video/reference/too-many-requests",
"title": "Too many requests.",
"status": 429
}Bad request error
{
"type": "https://docs.api.video/reference/invalid-attribute",
"title": "An attribute is invalid.",
"status": 400,
"detail": "This value must be of type string.",
"name": "metric"
}This error occurs when a parameter you provided does not exist, or isn't correct for this endpoint, has an invalid value.
{
"type": "https://docs.api.video/reference/request-invalid-query-parameter",
"title": "A query parameter is invalid.",
"status": 400,
"detail": "This field was not expected.",
"name": "from:2024-05-20T09:15:05+02:00"
}This error occurs when a query parameter you provided does not exist, isn't correct for this endpoint, or has an invalid value.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
detail string A solution for the error.
name string The name of the parameter that caused the error.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
context object (context) required
metric string Returns the metric you selected.
- Enum
-
- play
- play-rate
- start
- end
- impression
- Example
- "impression"
breakdown string Returns the dimension you selected.
- Enum
-
- media-id
- media-type
- continent
- country
- device-type
- operating-system
- browser
- Example
- "country"
timeframe object (timeframe) Returns the starting and ending date-times of the period you want analytics for.
from string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-28T11:15:07+00:00"
to string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-29T11:15:07+00:00"
data array[object] required
Returns an array of dimensions and their respective metrics.
object dimensionValue string Returns a specific value for the dimension you selected, based on the data. For example if you select continent as a dimension, then dimensionValue returns values like EU or "AZ".
metricValue number Returns the data for a specific dimension value.
pagination object (pagination) required
- Example
- { "itemsTotal": 123, "pagesTotal": 7, "pageSize": 20, "currentPage": 3, "currentPageItems": 20, "links": { "first": { "rel": "first", "uri": "/videos/search?currentPage=1&pageSize=20" }, "previous": { "rel": "previous", "uri": "/videos/search?currentPage=2&pageSize=20" }, "next": { "rel": "next", "uri": "/videos/search?currentPage=4&pageSize=20" }, "last": { "rel": "last", "uri": "/videos/search?currentPage=6&pageSize=20" } } }
itemsTotal int Total number of items that exist.
pagesTotal int Number of items listed in the current page.
pageSize int Maximum number of item per page.
currentPage int The current page index.
currentPageItems int The number of items on the current page.
links array[object (PaginationLink)] required
PaginationLink object (PaginationLink) rel string uri string - Format
- uri
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
Retrieve metrics over time
Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred
/data/timeseries/{metric} from string Use this query parameter to define the starting date-time of the period you want analytics for.
- If you do not set a value for
from, the default assigned value is 1 day ago, based on thetoparameter. - The maximum value is 30 days ago.
- The value you provide should follow the ATOM date-time format:
2024-02-05T00:00:00+01:00
- Format
- date-time
- Example
- "from=2024-02-05T00:00:00+01:00"
to string Use this query parameter to define the ending date-time of the period you want analytics for.
- If you do not set a value for
to, the default assigned value isnow. - The value for
tois a non-inclusive value: the API returns data before the date-time that you set.
- Format
- date-time
- Example
- "to=2024-02-06T00:00:00+01:00"
interval string Use this query parameter to define how granularity of the data. Possible values: hour, day.
Default: If no interval specified and the period (different between from and to) ≤ 2 days then hour, otherwise day.
If you do not set a value for
interval, and the period you set using thefromandtoparameters is less than or equals to 2 days, then the default assigned value ishour. Otherwise the API sets it today.
- Format
- date-time
- Example
- "to=2024-02-06T00:00:00+01:00"
filterBy string Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics. You must use camelCase for query parameters.
- If you do not set a value for
filterBy, the API returns the full dataset for your project.
These are the available breakdown dimensions:
mediaId: Returns analytics based on the unique identifiers of a video or a live stream.mediaType: Returns analytics based on the type of content. Possible values:videoandlive-stream.continent: Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. Possible values are:AS,AF,NA,SA,AN,EU,AZ.country: Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database.deviceType: Returns analytics based on the type of device used by the viewers. Possible response values are:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values includechrome,firefox,edge,opera.
- Example
- "filterBy[continent]=EU&filterBy[country]=FR&filterBy[browser]=Safari&filterBy[browser]=Firefox"
apiKey
metric string required
Use this path parameter to select a metric that you want analytics for.
playis the number of times your content has been played.play-rateis the ratio that calculates the number of plays your content receives divided by its impressions.startis the number of times playback was started.endis the number of times playback has ended with the content watch until the end.impressionis the number of times your content has been loaded and was ready for playback.
- Enum
-
- play
- play-rate
- start
- end
- impression
Responses
Success
{
"context": {
"metric": "play",
"interval": "hour",
"timeframe": {
"from": "2024-05-28T11:08:39+00:00",
"to": "2024-05-29T11:08:39+00:00"
}
},
"data": [
{
"emittedAt": "2024-05-29T07:00:00+00:00",
"metricValue": 2
},
{
"emittedAt": "2024-05-29T08:00:00+00:00",
"metricValue": 1
},
{
"emittedAt": "2024-05-29T09:00:00+00:00",
"metricValue": 1
}
],
"pagination": {
"currentPage": 1,
"currentPageItems": 3,
"pageSize": 25,
"pagesTotal": 1,
"itemsTotal": 3,
"links": [
{
"rel": "self",
"uri": "/data/timeseries/play?currentPage=1&pageSize=25"
},
{
"rel": "first",
"uri": "/data/timeseries/play?currentPage=1&pageSize=25"
},
{
"rel": "last",
"uri": "/data/timeseries/play?currentPage=1&pageSize=25"
}
]
}
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Unrecognized request URL
{
"type": "https://docs.api.video/reference/unrecognized-request-url",
"title": "Unrecognized request URL.",
"status": 404
}Too Many Requests
{
"type": "https://docs.api.video/reference/too-many-requests",
"title": "Too many requests.",
"status": 429
}Bad request error
{
"type": "https://docs.api.video/reference/invalid-attribute",
"title": "An attribute is invalid.",
"status": 400,
"detail": "This value must be of type string.",
"name": "metric"
}This error occurs when a parameter you provided does not exist, or isn't correct for this endpoint, has an invalid value.
{
"type": "https://docs.api.video/reference/request-invalid-query-parameter",
"title": "A query parameter is invalid.",
"status": 400,
"detail": "This field was not expected.",
"name": "from:2024-05-20T09:15:05+02:00"
}This error occurs when a query parameter you provided does not exist, isn't correct for this endpoint, or has an invalid value.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
type string A link to the error documentation.
title string A description of the error that occurred.
status int The HTTP status code.
detail string A solution for the error.
name string The name of the parameter that caused the error.
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
context object (context) required
metric string Returns the metric you selected.
- Enum
-
- play
- play-rate
- start
- end
- impression
- Example
- "impression"
interval string Returns the interval you selected.
- Enum
-
- hour
- day
- Example
- "day"
timeframe object (timeframe) Returns the starting and ending date-times of the period you want analytics for.
from string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-28T11:15:07+00:00"
to string Returns the starting date-time of the period you want analytics for in ATOM date-time format.
- Format
- date-time
- Example
- "2024-05-29T11:15:07+00:00"
data array[object] required
Returns an array of metrics and the timestamps .
object emittedAt string Returns the timestamp of the event that belongs to a specific metric in ATOM date-time format. For example, if you set play with an hour interval in your request, then emittedAt returns the hourly timestamps of every play event within the timeframe you defined.
metricValue number Returns the data for a specific metric value.
pagination object (pagination) required
- Example
- { "itemsTotal": 123, "pagesTotal": 7, "pageSize": 20, "currentPage": 3, "currentPageItems": 20, "links": { "first": { "rel": "first", "uri": "/videos/search?currentPage=1&pageSize=20" }, "previous": { "rel": "previous", "uri": "/videos/search?currentPage=2&pageSize=20" }, "next": { "rel": "next", "uri": "/videos/search?currentPage=4&pageSize=20" }, "last": { "rel": "last", "uri": "/videos/search?currentPage=6&pageSize=20" } } }
itemsTotal int Total number of items that exist.
pagesTotal int Number of items listed in the current page.
pageSize int Maximum number of item per page.
currentPage int The current page index.
currentPageItems int The number of items on the current page.
links array[object (PaginationLink)] required
PaginationLink object (PaginationLink) rel string uri string - Format
- uri
X-RateLimit-Limit int The request limit per minute.
X-RateLimit-Remaining int The number of available requests left for the current time window.
X-RateLimit-Retry-After int The number of seconds left until the current rate limit window resets.
Was this page helpful?