Analytics
/data/metrics/{metric}/{aggregation}Retrieve aggregated metrics
Retrieve time-based and countable metrics like average watch time or the number of impressions over a certain period of time.
fromstringUse 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"
tostringUse 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"
filterByobject (filterBy)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/totalor/data/buckets/play-total/media-id.
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. You must use the ISO-3166 alpha2 format, for exampleEU. 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. You must use the ISO-3166 alpha2 format, for exampleFR.deviceType: Returns analytics based on the type of device used by the viewers. Response values can include:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values can includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values can includechrome,firefox,edge,opera.tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"
mediaIdarray[string]Returns analytics based on the unique identifiers of a video or a live stream.
- Example
- [ "vi4blUQJFrYWbaG44NChkH27" ]
stringmediaTypestring- Enum
- video
- live-stream
- Example
- "video"
continentarray[string]Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.
- Example
- [ "EU" ]
string- Enum
- AS
- AF
- NA
- SA
- AN
- EU
- AZ
countryarray[string]Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.
- Example
- [ "FR" ]
stringdeviceTypearray[string]Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
- Example
- [ "computer" ]
stringoperatingSystemarray[string]Returns analytics based on the operating system used by the viewers. Response values can include windows, mac osx, android, ios, linux.
- Example
- [ "windows" ]
stringbrowserarray[string]Returns analytics based on the browser used by the viewers. Response values can include chrome, firefox, edge, opera.
- Example
- [ "firefox" ]
stringtagstringReturns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "Cool videos"
apiKey
metricstringrequired
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
aggregationstringrequired
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
Unrecognized request URL
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Too Many Requests
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Bad request error
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
detailstringA solution for the error.
namestringThe name of the parameter that caused the error.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Success
contextobject (context)required
metricstringReturns the metric you selected.
- Enum
- play
- start
- end
- impression
- impression-time
- watch-time
- Example
- "impression"
aggregationstringReturns the aggregation you selected.
- Enum
- count
- rate
- total
- average
- sum
- Example
- "count"
timeframeobject (timeframe)Returns the starting and ending date-times of the period you want analytics for.
fromstringReturns 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"
tostringReturns 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"
datanumberrequired
- Example
- "356.2"
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Request examples
FilterBy2 filterBy = new FilterBy2();
filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");
AnalyticsAggregatedMetricsResponse res = apiClient.analytics().getAggregatedMetrics("play", "total").filterBy(filterBy).execute();
System.out.println(res.getData());
const res = await client.analytics.getAggregatedMetrics({
aggregation: 'total',
metric: 'play',
filterBy: {
browser: ['chrome', 'firefox'],
continent: ['EU', 'AF'],
tag: 'test',
},
});
console.log(res.data);
FilterBy2 filterBy = new FilterBy2
{
continent = new List<string> { "EU", "US" },
devicetype = new List<string> { "phone" },
tag = "test"
};
AnalyticsAggregatedMetricsResponse res = apiClient.Analytics()
.getAggregatedMetrics("play", "total").From(new DateTime(2024, 7, 1)).FilterBy(filterBy).execute();
res, err := cl.Analytics.GetAggregatedMetrics("play", "day", AnalyticsApiGetAggregatedMetricsRequest{
filterBy: &FilterBy2{
Continent: &[]string{"EU", "AA"},
DeviceType: &[]string{"computer", "phone"},
Tag: PtrString("tag"),
},
})
res = self.api.get_aggregated_metrics(metric='play', aggregation='count', filter_by=FilterBy2(
device_type=["computer", "phone"],
tag="test",
),
)
AnalyticsAPI.getAggregatedMetrics(
metric: .play,
aggregation: .total,
filterBy: FilterBy2(
continent: [.an, .eu],
tag: "test"
)
) { analytics, error in
// ...
}
Response examples
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
}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.
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
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
/data/buckets/{metric}/{breakdown}Retrieve metrics in a breakdown of dimensions
Retrieve detailed analytics play-rate and number of impressions segmented by dimensions like country or device type.
fromstringUse 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"
tostringUse 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"
sortBystringUse this parameter to choose which field the API will use to sort the analytics data.
These are the available fields to sort by:
metricValue: Sorts the results based on the metric you selected in your request.dimensionValue: Sorts the results based on the dimension you selected in your request.
- Enum
- metricValue
- dimensionValue
- Example
- "metricValue"
sortOrderstringUse this parameter to define the sort order of results.
These are the available sort orders:
asc: Sorts the results in ascending order:A to Zand0 to 9.desc: Sorts the results in descending order:Z to Aand9 to 0.
- Enum
- asc
- desc
- Example
- "asc"
filterByobject (filterBy)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/totalor/data/buckets/play-total/media-id.
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. You must use the ISO-3166 alpha2 format, for exampleEU. 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. You must use the ISO-3166 alpha2 format, for exampleFR.deviceType: Returns analytics based on the type of device used by the viewers. Response values can include:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values can includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values can includechrome,firefox,edge,opera.tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"
mediaIdarray[string]Returns analytics based on the unique identifiers of a video or a live stream.
- Example
- [ "vi4blUQJFrYWbaG44NChkH27" ]
stringmediaTypestring- Enum
- video
- live-stream
- Example
- "video"
continentarray[string]Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.
- Example
- [ "EU" ]
string- Enum
- AS
- AF
- NA
- SA
- AN
- EU
- AZ
countryarray[string]Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.
- Example
- [ "FR" ]
stringdeviceTypearray[string]Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
- Example
- [ "computer" ]
stringoperatingSystemarray[string]Returns analytics based on the operating system used by the viewers. Response values can include windows, mac osx, android, ios, linux.
- Example
- [ "windows" ]
stringbrowserarray[string]Returns analytics based on the browser used by the viewers. Response values can include chrome, firefox, edge, opera.
- Example
- [ "firefox" ]
stringtagstringReturns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "Cool videos"
currentPageintChoose the number of search results to return per page. Minimum value: 1
- Default
- 1
- Example
- 2
pageSizeintResults per page. Allowed values 1-100, default is 25.
- Default
- 25
- Example
- 30
apiKey
metricstringrequired
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
breakdownstringrequired
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. Response values can include:computer,phone,tablet,tv,console,wearable,unknown.operating-system: Returns analytics based on the operating system used by the viewers. Response values can includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values can includechrome,firefox,edge,opera.
- Enum
- media-id
- media-type
- continent
- country
- device-type
- operating-system
- browser
Responses
Unrecognized request URL
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Too Many Requests
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Bad request error
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
detailstringA solution for the error.
namestringThe name of the parameter that caused the error.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Success
contextobject (context)required
metricstringReturns the metric you selected.
- Enum
- play
- play-rate
- start
- end
- impression
- Example
- "impression"
breakdownstringReturns the dimension you selected.
- Enum
- media-id
- media-type
- continent
- country
- device-type
- operating-system
- browser
- Example
- "country"
timeframeobject (timeframe)Returns the starting and ending date-times of the period you want analytics for.
fromstringReturns 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"
tostringReturns 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"
dataarray[object]required
Returns an array of dimensions and their respective metrics.
objectdimensionValuestringReturns 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".
metricValuenumberReturns the data for a specific dimension value.
paginationobject (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" } } }
itemsTotalintTotal number of items that exist.
pagesTotalintNumber of items listed in the current page.
pageSizeintMaximum number of item per page.
currentPageintThe current page index.
currentPageItemsintThe number of items on the current page.
linksarray[object (PaginationLink)]required
PaginationLinkobject (PaginationLink)relstringuristring- Format
- uri
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Request examples
FilterBy2 filterBy = new FilterBy2();
filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");
Page<AnalyticsMetricsBreakdownResponseData> res = apiClient.analytics().getMetricsBreakdown("play", "media-id").filterBy(filterBy).pageSize(30).execute();
for (AnalyticsMetricsBreakdownResponseData item : res.getItems()) {
System.out.println(item.getDimensionValue() + ": " + item.getMetricValue());
}
const res = await client.analytics.getMetricsBreakdown({
breakdown: 'continent',
metric: 'play',
filterBy: {
browser: ['chrome', 'firefox'],
continent: ['EU', 'AF'],
tag: 'test',
},
});
console.log(res.data);
FilterBy2 filterBy = new FilterBy2
{
continent = new List<string> { "EU", "US" },
devicetype = new List<string> { "phone" },
tag = "test"
};
Page<AnalyticsMetricsBreakdownResponseData> page = apiClient.Analytics()
.getMetricsBreakdown("play", "continent").From(new DateTime(2024, 7, 1)).FilterBy(filterBy).execute();
res, err := cl.Analytics.GetMetricsBreakdown("play", "continent", AnalyticsApiGetMetricsBreakdownRequest{
filterBy: &FilterBy2{
Continent: &[]string{"EU", "AA"},
DeviceType: &[]string{"computer", "phone"},
Tag: PtrString("tag"),
},
})
res = self.api.get_metrics_breakdown(metric='play', breakdown='continent', filter_by=FilterBy2(
device_type=["computer", "phone"],
tag="test",
),
)
AnalyticsAPI.getMetricsBreakdown(
metric: .play,
breakdown: .browser,
filterBy: FilterBy2(
continent: [.an, .eu],
tag: "test"
)
) { analytics, error in
// ...
}
Response examples
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"
}
]
}
}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.
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
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
/data/timeseries/{metric}Retrieve metrics over time
Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred
fromstringUse 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"
tostringUse 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"
intervalstringUse 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.
- Enum
- hour
- day
- Example
- "hour"
sortBystringUse this parameter to choose which field the API will use to sort the analytics data.
These are the available fields to sort by:
metricValue: Sorts the results based on the metric you selected in your request.emittedAt: Sorts the results based on the timestamp of the event in ATOM date-time format.
- Enum
- metricValue
- emittedAt
- Example
- "metricValue"
sortOrderstringUse this parameter to define the sort order of results.
These are the available sort orders:
asc: Sorts the results in ascending order:A to Zand0 to 9.desc: Sorts the results in descending order:Z to Aand9 to 0.
- Enum
- asc
- desc
- Example
- "asc"
filterByobject (filterBy)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/totalor/data/buckets/play-total/media-id.
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. You must use the ISO-3166 alpha2 format, for exampleEU. 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. You must use the ISO-3166 alpha2 format, for exampleFR.deviceType: Returns analytics based on the type of device used by the viewers. Response values can include:computer,phone,tablet,tv,console,wearable,unknown.operatingSystem: Returns analytics based on the operating system used by the viewers. Response values can includewindows,mac osx,android,ios,linux.browser: Returns analytics based on the browser used by the viewers. Response values can includechrome,firefox,edge,opera.tag: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "filterBy[country]=FR&filterBy[operatingSystem]=windows&filterBy[browser][]=firefox&filterBy[browser][]=chrome&filterBy[tag]=Cool videos"
mediaIdarray[string]Returns analytics based on the unique identifiers of a video or a live stream.
- Example
- [ "vi4blUQJFrYWbaG44NChkH27" ]
stringmediaTypestring- Enum
- video
- live-stream
- Example
- "video"
continentarray[string]Returns analytics based on the viewers' continent. The list of supported continents names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example EU.
- Example
- [ "EU" ]
string- Enum
- AS
- AF
- NA
- SA
- AN
- EU
- AZ
countryarray[string]Returns analytics based on the viewers' country. The list of supported country names are based on the GeoNames public database. You must use the ISO-3166 alpha2 format, for example FR.
- Example
- [ "FR" ]
stringdeviceTypearray[string]Returns analytics based on the type of device used by the viewers. Response values can include: computer, phone, tablet, tv, console, wearable, unknown.
- Example
- [ "computer" ]
stringoperatingSystemarray[string]Returns analytics based on the operating system used by the viewers. Response values can include windows, mac osx, android, ios, linux.
- Example
- [ "windows" ]
stringbrowserarray[string]Returns analytics based on the browser used by the viewers. Response values can include chrome, firefox, edge, opera.
- Example
- [ "firefox" ]
stringtagstringReturns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos here.
- Example
- "Cool videos"
currentPageintChoose the number of search results to return per page. Minimum value: 1
- Default
- 1
- Example
- 2
pageSizeintResults per page. Allowed values 1-100, default is 25.
- Default
- 25
- Example
- 30
apiKey
metricstringrequired
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
Unrecognized request URL
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Too Many Requests
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Bad request error
typestringA link to the error documentation.
titlestringA description of the error that occurred.
statusintThe HTTP status code.
detailstringA solution for the error.
namestringThe name of the parameter that caused the error.
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Success
contextobject (context)required
metricstringReturns the metric you selected.
- Enum
- play
- play-rate
- start
- end
- impression
- Example
- "impression"
intervalstringReturns the interval you selected.
- Enum
- hour
- day
- Example
- "day"
timeframeobject (timeframe)Returns the starting and ending date-times of the period you want analytics for.
fromstringReturns 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"
tostringReturns 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"
dataarray[object]required
Returns an array of metrics and the timestamps .
objectemittedAtstringReturns 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.
metricValuenumberReturns the data for a specific metric value.
paginationobject (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" } } }
itemsTotalintTotal number of items that exist.
pagesTotalintNumber of items listed in the current page.
pageSizeintMaximum number of item per page.
currentPageintThe current page index.
currentPageItemsintThe number of items on the current page.
linksarray[object (PaginationLink)]required
PaginationLinkobject (PaginationLink)relstringuristring- Format
- uri
X-RateLimit-LimitintThe request limit per minute.
X-RateLimit-RemainingintThe number of available requests left for the current time window.
X-RateLimit-Retry-AfterintThe number of seconds left until the current rate limit window resets.
Request examples
FilterBy2 filterBy = new FilterBy2();
filterBy.setBrowser(Collections.singletonList("Chrome"));
filterBy.setContinent(Arrays.asList(FilterBy2.ContinentEnum.NA, FilterBy2.ContinentEnum.EU));
filterBy.setMediaType(FilterBy2.MediaTypeEnum.VIDEO);
filterBy.setTag("test");
Page<AnalyticsMetricsOverTimeResponseData> res = apiClient.analytics().getMetricsOverTime("play").filterBy(filterBy).pageSize(30).execute();
for (AnalyticsMetricsOverTimeResponseData item : res.getItems()) {
System.out.println(item.getEmittedAt() + ": " + item.getMetricValue());
}
const res = await client.analytics.getMetricsOverTime({
metric: 'play',
filterBy: {
mediaType: 'video',
browser: ['chrome', 'firefox'],
continent: ['EU', 'AF'],
tag: "test",
},
});
console.log(res);
FilterBy2 filterBy = new FilterBy2
{
continent = new List<string> { "EU", "US" },
devicetype = new List<string> { "phone" },
tag = "test"
};
Page<AnalyticsMetricsOverTimeResponseData> res = apiClient.Analytics()
.getMetricsOverTime("play").From(new DateTime(2024, 7, 1)).FilterBy(filterBy).execute();
res, err := cl.Analytics.GetMetricsOverTime("play", AnalyticsApiGetMetricsOverTimeRequest{
filterBy: &FilterBy2{
Continent: &[]string{"EU", "AA"},
DeviceType: &[]string{"computer", "phone"},
Tag: PtrString("tag"),
},
})
res = self.api.get_metrics_over_time(metric='play', filter_by=FilterBy2(
device_type=["computer", "phone"],
tag="test",
),
)
AnalyticsAPI.getMetricsOverTime(
metric: .play,
filterBy: FilterBy2(
continent: [.an, .eu],
tag: "test"
)
) { analytics, error in
// ...
}
Response examples
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"
}
]
}
}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.
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
}Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Was this page helpful?