Sign in
latestOpenAPI 3.0.02026-07-175989869.3 KB

45ec26f342b6

Analytics

Retrieve metrics over time

Retrieve countable metrics like the number of plays or impressions, grouped by the time at which they occurred

get/data/timeseries/{metric}

Path parameters

metric'play' | 'play-rate' | 'start' | 'end' | 'impression' | 'ccv-peak' | 'ccv-average' | 'view' 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.

Query parameters

fromstring date-time

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
tostring date-time

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.
interval'minute' | 'hour' | 'day'

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.
sortBy'metricValue' | 'emittedAt'

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.
sortOrder'asc' | 'desc'

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.
uniqueboolean

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.

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'3s' | '5s' | '10s' | '30s'

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.
currentPageinteger

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

pageSizeinteger

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

Parameters

#/components/parameters/filterBy_2 — unresolved $ref

Response

Success

Example response

{
  "pagination": {
    "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"
      }
    }
  },
  "data": [
    {
      "emittedAt": "emittedAt",
      "metricValue": 0.8008282
    },
    {
      "emittedAt": "emittedAt",
      "metricValue": 0.8008282
    }
  ],
  "context": {
    "timeframe": {
      "from": "2024-05-28T11:15:07Z",
      "to": "2024-05-29T11:15:07Z"
    },
    "metric": "impression",
    "interval": "day"
  }
}