Analytics overview

api.video's Analytics enables you to retrieve complex event data about your videos and live streams.

For example, you can:

• get the number of impressions for your content over a period of time like the current day, the past week, or the last 30 days,
• break down the number of plays for a live stream through dimensions like country, device type, OS, or browser,
• or retrieve play-rate trends over time for your videos.

Use this data to understand your audience, or integrate the data directly into your own application to display it to your viewers.

Visit the Analytics page on the Dashboard to get started and see your data visualized, or jump into the API reference and see how you can work with the data through our API!

How to use

api.video offers 3 dedicated API endpoints that you can use to programmatically retrieve data about your content:

Visit the API reference for details on how you can interact with the Analytics API, including request parameters and sample responses.

Here are some real-world questions where metrics and dimensions from Analytics can help you find the answers:

• E-learning

  • How many students have played my courses? → play
  • How many students have started watching a course? → start
  • What is the average watch duration of my course? → watch-time

• Short-form videos

  • Have my viewers watched the first N videos on the feed until the end? → end
  • How many times have my viewers watched a specific video? → play-total + media-id
  • What was the highest number of concurrent viewers last week? → from + ccv-peak + unique
  • What videos have the longest view duration? → view + media-id + sortBy[metricValue] + sortOrder=desc

• Advertising

  • How many impressions have my ads generated? → impression
  • Is my ad displayed fast in Asia? → impression-time + continent
  • From the websites where my video ad is embedded, which ones got the most views? → view + referrer + sortBy[metricValue]

Requirements

How it works

Analytics uses player events to analyze and segment your viewers' interactions with your content. Here are some key aspects:

• By default, api.video retains analytics data for 30 days. You can extend data retention to 3 months or 12 months through the Analytics page in the Dashboard - click on the 3M or 12M buttons to get started!
• Player events are generated when your viewers engage with a video or live stream session.
• Data is refreshed in real time, with a frequency of <5s.
• Data does not carry over from the previous versions of Analytics, and unique viewer data starts only from 2024-08-14.
• unique viewers are only unique for a day.
• Video re-plays using the dedicated re-play button in the player do not generate events.
• On web, if a user watches a video, refreshes the browser tab, then plays the video again, a new event is generated.

Sessions

User sessions affect how data like the number of viewers is counted.

• For web users, a browser tab counts as one user session.

• For mobile users, a session starts when an app is launched. Apps going in the background remain in session. A new session starts when an app is destroyed, and then launches again.

Aggregations vs. timeseries

The /data/metrics/{metric}/{aggregation} and /data/timeseries/{metric} endpoints can return very similar data. Here's a concrete example on how to understand the fundamental difference.

Let's get the number of plays for a video from the last 2 days. We can use both endpoints to get this data:

• /data/metrics/play/sum → the value of the play metric aggregated to sum
• /data/timeseries/play → the value of the play metric over time

We will filter for a specific video using filterBy[mediaId]={videoId}, and set a short, 2-day timeframe using from and to.

Let's compare the results:

{
  "context": {
    "metric": "play",
    "aggregation": "sum",
    "timeframe": {
      "from": "2024-10-01T00:00:00+00",
      "to": "2024-10-02T23:59:59+00:00"
    }
  },
  "data": 1
}

Notice that /metrics/play/sum returns only 1 play, and returns 2 plays. How so? Check the values of the emittedAt fields in the /timeseries/play example above: the difference is only 2 minutes, but on two different calendar days.

• The timeseries endpoint counts the number of events based on a set interval, which is day by default. This means that a user watching the same video on two calendar days generates 2 play events: 1 for each day.
• The metrics endpoint sums up the number of play events. This means that if the user watches the video once, they generate only 1 play event - even if that event falls on the boundary of 2 calendar days.

Testing

You can test the Analytics endpoints in api.video's sandbox environment. Check out Environments for more details. The sandbox environment returns data from the last 24 hours.

What's next

Check out the API reference for sample responses and errors, and more details about using the Analytics endpoints.

If you have any questions, reach out to the team using the chatbox!