Analytics

get /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.

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 the to parameter.
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

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 is now .
The API ignores this parameter when you call /data/metrics/play/total .
The value for to is a non-inclusive value: the API returns data before the date-time that you set.

Format: date-time

unique boolean

Use this query parameter to control how viewer data is counted:

true means that a single user watching multiple times counts as 1 unique viewer
false means that all views count, even if from the same user.

The API accepts this parameter only when you use the ccv or view metric.

Viewers are unique for 1 day.

The API determines uniqueness based on a viewer's user-agent and IP address. This means that the API can filter viewers using multiple tabs to watch the same video multiple times, but cannot filter for viewers who use multiple browsers to watch the same content multiple times.

viewDuration string

Use this query parameter to define how many seconds a view has to last to be counted in analytics data.

You can only use this parameter with the view metric.
The accepted values are 3s , 5s , 10s , and 30s .
If you do not set this parameter, the API defaults to 5s .

Enum: 3s

5s

10s

30s

filterBy object

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 mediaId and mediaType filters when you call /data/metrics/play/total or /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: video and live-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 example EU . 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 example FR .
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 include windows , mac osx , android , ios , linux .
browser : Returns analytics based on the browser used by the viewers. Response values can include chrome , 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 .
referrer : Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

mediaId array

Returns analytics based on the unique identifiers of a video or a live stream.

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaType string

Enum: video

live-stream
Example: "video"

continent array

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" ]

country array

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" ]

deviceType array

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" ]

operatingSystem array

Returns analytics based on the operating system used by the viewers. Response values can include windows , mac osx , android , ios , linux .

Example: [ "windows" ]

browser array

Returns analytics based on the browser used by the viewers. Response values can include chrome , firefox , edge , opera .

Example: [ "firefox" ]

tag string

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: "Cool videos"

referrer array

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

metric string required

Use this path parameter to select a metric that you want analytics for.

play is the number of times your content has been played. You can use the aggregations count , rate , and total with the play metric.
start is the number of times playback was started. You can use the aggregation count with this metric.
end is the number of times playback has ended with the content watch until the end. You can use the aggregation count with this metric.
impression is the number of times your content has been loaded and was ready for playback. You can use the aggregation count with this metric.
impression-time is the time in milliseconds that your content was loading for until the first video frame is displayed. You can use the aggregations average and sum with this metric.
watch-time is the cumulative time in seconds that the user has spent watching your content. You can use the aggregations average and sum with this metric.
ccv : is the number of concurrent viewers, or users watching at the same time.
view : the total number of viewers until this point in time.

Enum: play

start

end

impression

impression-time

watch-time

ccv

view

aggregation string required

Use this path parameter to define a way of collecting data for the metric that you want analytics for.

count returns the overall number of events for the play metric.
rate returns the ratio that calculates the number of plays your content receives divided by its impressions. This aggregation can be used only with the play metric.
total calculates the total number of events for the play metric.
average calculates an average value for the selected metric.
sum adds up the total value of the select metric.
peak shows the highest value of the ccv metric in the timeframe of your request. You can use this aggregation only with the ccv metric.
live shows the highest value of the ccv metric from the last 20 seconds. You can use this aggregation only with the ccv metric.

Enum: count

rate

total

average

sum

peak

live

Responses

Success

Response body Headers

context object required

metric string

Returns the metric and relevant parameters you selected.

Enum: play

start

end

impression

impression-time

watch-time

ccv

unique-ccv

view-3

view-5

view-10

view-30

unique-view

unique-view-3

unique-view-5

unique-view-10

unique-view-30
Example: "impression"

aggregation string

Returns the aggregation you selected.

Enum: count

rate

total

average

sum
Example: "count"

timeframe object

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.

Bad request error

Response body Headers

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.

Unrecognized request URL

Response body Headers

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.

Too Many Requests

Response body Headers

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.

Request examples

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"),
  },
})

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);

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.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This value should not contain more than 2048 characters.",
  "name": "filterBy[referrer]"
}

Occurs when the value of referrer in your query is too long.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".",
  "name": "viewDuration"
}

Occurs when the value of viewDuration is incorrect.

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
}

get /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.

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 the to parameter.
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

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 is now .
The value for to is a non-inclusive value: the API returns data before the date-time that you set.

Format: date-time

sortBy string

Use 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

sortOrder string

Use this parameter to define the sort order of results.

These are the available sort orders:

asc : Sorts the results in ascending order: A to Z and 0 to 9 .
desc : Sorts the results in descending order: Z to A and 9 to 0 .

Enum: asc

desc

unique boolean

Use this query parameter to control how viewer data is counted:

true means that a single user watching multiple times counts as 1 unique viewer
false means that all views count, even if from the same user.

The API accepts this parameter only when you use the ccv-peak , ccv-average , or view metric.

Viewers are unique for 1 day.

viewDuration string

Use this query parameter to define how many seconds a view has to last to be counted in analytics data.

You can only use this parameter together with the view metric.
The accepted values are 3s , 5s , 10s , and 30s .
If you do not set this parameter, the API defaults to 5s .

Enum: 3s

5s

10s

30s

filterBy object

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 mediaId and mediaType filters when you call /data/metrics/play/total or /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: video and live-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 example EU . 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 example FR .
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 include windows , mac osx , android , ios , linux .
browser : Returns analytics based on the browser used by the viewers. Response values can include chrome , 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 .
referrer : Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

mediaId array

Returns analytics based on the unique identifiers of a video or a live stream.

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaType string

Enum: video

live-stream
Example: "video"

continent array

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" ]

country array

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" ]

deviceType array

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" ]

operatingSystem array

Returns analytics based on the operating system used by the viewers. Response values can include windows , mac osx , android , ios , linux .

Example: [ "windows" ]

browser array

Returns analytics based on the browser used by the viewers. Response values can include chrome , firefox , edge , opera .

Example: [ "firefox" ]

tag string

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: "Cool videos"

referrer array

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default: 1

pageSize int

Results per page. Allowed values 1-100, default is 25.

Default: 25

metric string required

Use this path parameter to select a metric that you want analytics for.

play is the number of times your content has been played.
play-rate is the ratio that calculates the number of plays your content receives divided by its impressions.
play-total is the total number of times a specific content has been played. You can only use the media-id breakdown with this metric.
start is the number of times playback was started.
end is the number of times playback has ended with the content watch until the end.
impression is the number of times your content has been loaded and was ready for playback.
ccv-peak is the highest number of concurrent viewers in the timeframe of your request.
ccv-average is the average number of concurrent viewers in the timeframe of your request.
view is the total number of viewers until this point in time.

Enum: play

play-rate

play-total

start

end

impression

ccv-peak

ccv-average

view

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: video and live-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 include windows , mac osx , android , ios , linux .
browser : Returns analytics based on the browser used by the viewers. Response values can include chrome , firefox , edge , opera .
referrer : Returns the URL where the view originates from, for example a website where the video is embedded. View events from Android and iOS return empty strings as the value for referrer .

Enum: media-id

media-type

continent

country

device-type

operating-system

browser

referrer

Responses

Success

Response body Headers

context object required

metric string

Returns the metric and relevant parameters you selected.

Enum: play

play-rate

start

end

impression

ccv-average

ccv-peak

unique-ccv-average

unique-ccv-peak

view-3

view-5

view-10

view-30

unique-view

unique-view-3

unique-view-5

unique-view-10

unique-view-30
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

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 required

Returns an array of dimensions and their respective metrics.

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 required

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.

Bad request error

Response body Headers

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.

Unrecognized request URL

Response body Headers

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.

Too Many Requests

Response body Headers

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.

Request examples

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"),
  },
})

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);

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&currentPage=1&pageSize=25"
      },
      {
        "rel": "first",
        "uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00&currentPage=1&pageSize=25"
      },
      {
        "rel": "last",
        "uri": "/data/buckets/play/country?from=2024-04-28T09%3A15%3A05%2B02%3A00&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.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This value should not contain more than 2048 characters.",
  "name": "filterBy[referrer]"
}

Occurs when the value of referrer in your query is too long.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".",
  "name": "viewDuration"
}

Occurs when the value of viewDuration is incorrect.

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
}

get /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

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 the to parameter.
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

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 is now .
The value for to is a non-inclusive value: the API returns data before the date-time that you set.

Format: date-time

interval string

Use this query parameter to define the granularity of the data. Possible values: minute , hour , day .

If you do not set a value for interval , and the period you set using the from and to parameters is less than or equals to 2 days, then the default assigned value is hour . Otherwise the API sets it to day .
When you set minute as interval, the timeframe you define with the from and to parameters must be less than 60 minutes.

Enum: minute

hour

day

sortBy string

Use 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

sortOrder string

Use this parameter to define the sort order of results.

These are the available sort orders:

asc : Sorts the results in ascending order: A to Z and 0 to 9 .
desc : Sorts the results in descending order: Z to A and 9 to 0 .

Enum: asc

desc

unique boolean

Use this query parameter to control how viewer data is counted:

true means that a single user watching multiple times counts as 1 unique viewer
false means that all views count, even if from the same user.

The API accepts this parameter only when you use the ccv-peak , ccv-average , or view metric.

Viewers are unique for 1 day.

viewDuration string

Use this query parameter to define how many seconds a view has to last to be counted in analytics data.

You can only use this parameter together with the view metric.
The accepted values are 3s , 5s , 10s , and 30s .
If you do not set this parameter, the API defaults to 5s .

Enum: 3s

5s

10s

30s

filterBy object

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 mediaId and mediaType filters when you call /data/metrics/play/total or /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: video and live-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 example EU . 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 example FR .
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 include windows , mac osx , android , ios , linux .
browser : Returns analytics based on the browser used by the viewers. Response values can include chrome , 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 .
referrer : Filters data based on the URL where the view is originating from. Accepts an empty string as a value to filter view events where no referrer is available.

mediaId array

Returns analytics based on the unique identifiers of a video or a live stream.

Example: [ "vi4blUQJFrYWbaG44NChkH27" ]

mediaType string

Enum: video

live-stream
Example: "video"

continent array

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" ]

country array

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" ]

deviceType array

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" ]

operatingSystem array

Returns analytics based on the operating system used by the viewers. Response values can include windows , mac osx , android , ios , linux .

Example: [ "windows" ]

browser array

Returns analytics based on the browser used by the viewers. Response values can include chrome , firefox , edge , opera .

Example: [ "firefox" ]

tag string

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: "Cool videos"

referrer array

Filters data based on the URL where the view is originating from. This filter parameter accepts an empty string to filter view events where no referrer is available.

The API filters for exact matches. Include the trailing / characters if needed.
The URLs you add must be URL encoded.

Example: [ "https%3A%2F%2Fmy-awesome-videos.com" ]

currentPage int

Choose the number of search results to return per page. Minimum value: 1

Default: 1

pageSize int

Results per page. Allowed values 1-100, default is 25.

Default: 25

metric string required

Use this path parameter to select a metric that you want analytics for.

play is the number of times your content has been played.
play-rate is the ratio that calculates the number of plays your content receives divided by its impressions.
start is the number of times playback was started.
end is the number of times playback has ended with the content watch until the end.
impression is the number of times your content has been loaded and was ready for playback.
ccv-peak is the highest number of concurrent viewers in the timeframe of your request.
ccv-average is the average number of concurrent viewers in the timeframe of your request.
view is the total number of viewers.

Enum: play

play-rate

start

end

impression

ccv-peak

ccv-average

view

Responses

Success

Response body Headers

context object required

metric string

Returns the metric and relevant parameters you selected.

Enum: play

play-rate

start

end

impression

ccv-average

ccv-peak

unique-ccv-average

unique-ccv-peak

view-3

view-5

view-10

view-30

unique-view

unique-view-3

unique-view-5

unique-view-10

unique-view-30
Example: "impression"

interval string

Returns the interval you selected.

Enum: minute

hour

day
Example: "day"

timeframe object

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 required

Returns an array of metrics and the timestamps.

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 required

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.

Bad request error

Response body Headers

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.

Unrecognized request URL

Response body Headers

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.

Too Many Requests

Response body Headers

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.

Request examples

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"),
  },
})

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);

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.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This interval is invalid. Use one of \"minute\", \"hour\", \"day\".",
  "name": "interval"
}

Occurs when the value you set for interval is not minute , hour , or day .

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This interval cannot be used with a timeframe over 60 minutes.",
  "name": "interval"
}

Occurs when you set minute as interval, and a timeframe that is longer than 60 minutes.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This value should not contain more than 2048 characters.",
  "name": "filterBy[referrer]"
}

Occurs when the value of referrer in your query is too long.

{
  "type": "https://docs.api.video/reference/request-invalid-query-parameter",
  "title": "A query parameter is invalid.",
  "status": 400,
  "detail": "This view duration is invalid. Use one of \"3s\", \"5s\", \"10s\", \"30s\".",
  "name": "viewDuration"
}

Occurs when the value of viewDuration is incorrect.

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
}