Retrieving raw statistics for videos, live streams, and players

api.video offers extensive analytics information for videos on demand, live streams, and the individual player sessions that occur for either. You can retrieve a list of all player sessions for a video or live stream, then dive into individual player sessions for more information.

Associated API reference documentation

Choose an api.video client

The clients offered by api.video include:

Installation

To install your selected client, do the following:

go get github.com/apivideo/api.video-go-client
composer require api-video/php-api-client
npm install @api.video/nodejs-client --save

...or with yarn: 
  
yarn add @api.video/nodejs-client
pip install api.video
Using Nuget
  
Install-Package ApiVideo

Retrieve your API key

You'll need your API key to get started. You can sign up for one here: Get your api.video API key!. Then do the following:

  1. Log in to the api.video dashboard.
  2. From the list of choices on the left, make sure you are on API Keys
  3. You will always be able to choose to use your Sandbox API key. If you want to use the Production API key instead, enter your credit card information.
  4. Grab the key you want, and you're ready to get started!

Retrieve all sessions for a video

Using the unique video ID, you can grab a complete list of all the different player sessions associated with a video. You must use api.video's player to get access to these details. If you don't want an exhaustive list of everything, you can also filter by time period. The code sample for this is:

curl --request GET \
     --url 'https://ws.api.video/analytics/videos/vi4k0jvEUuaTdRAEjQ4Prklg?period=2022-01-01&metadata\[hats\]=green&currentPage=1&pageSize=25' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MjQzMTkuMDk2NjY1LCJuYmYiOjE2NDI4MjQzMTkuMDk2NjY1LCJleHAiOjE2NDI4Mjc5MTkuMDk2NjY1LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.rfchf3btbMTzSukcwhUS0u4fNY4Q3g1JpoMeIz_Dls1ADmqDdKw7yBOE893C7cagb0lpuvUJvhuhgusLStsJ4nqzTveDeM2oPBQBNJjzwaJZNrImTPD4mif7Tzgxvn1_jQJA5L4gQhjd7frCIJW1yAwywrtiDPbxiWNp8fVl7r_QILjZZfslxy-kblPrHJ20Zix9VURqkGIORY5G_457nHSV9Atks1sUlt49E8b_g3jORja3MnznXBS0-0dksz2K62-QMe1_dk78V9JwbLeydqcr15M1jDLA3H6qFGI7GTsTDdZ5jKLhg5OR6yeSHFysqr3kOteTqAGdp3JuTrpZIA'
package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
    req := apivideosdk.RawStatisticsApiListVideoSessionsRequest{}
    
    req.VideoId("vi4k0jvEUuaTdRAEjQ4Prklg") // string | The unique identifier for the video you want to retrieve session information for.
    req.Period("period_example") // string | Period must have one of the following formats:  - For a day : 2018-01-01, - For a week: 2018-W01,  - For a month: 2018-01 - For a year: 2018 For a range period:  -  Date range: 2018-01-01/2018-01-15 
    req.Metadata(map[string]string{"key": "TODO"}) // map[string]string | Metadata and [Dynamic Metadata](https://api.video/blog/endpoints/dynamic-metadata) filter. Send an array of key value pairs you want to filter sessios with.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.RawStatistics.ListVideoSessions(videoId string, req)
    

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `RawStatistics.ListVideoSessions``: %v\n", err)
    }
    // response from `ListVideoSessions`: RawStatisticsListSessionsResponse
    fmt.Fprintf(os.Stdout, "Response from `RawStatistics.ListVideoSessions`: %v\n", res)
}
<?php
require __DIR__ .'/vendor/autoload.php';

use Symfony\Component\HttpClient\Psr18Client;
use ApiVideo\Client\Client;
use ApiVideo\Client\Model\RawStatisticsApi;

$apiKey = 'your API key here';
$apiVideoEndpoint = 'https://ws.api.video';

$httpClient = new \Symfony\Component\HttpClient\Psr18Client();
$client = new ApiVideo\Client\Client(
    $apiVideoEndpoint,
    $apiKey,
    $httpClient
);

$rawStatistics = $client->rawStatistics()->listVideoSessions('video ID');

print($rawStatistics);
const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const videoId = 'vi4k0jvEUuaTdRAEjQ4Prklg'; // The unique identifier for the video you want to retrieve session information for.
        const period = 'period_example'; // Period must have one of the following formats:  - For a day : 2018-01-01, - For a week: 2018-W01,  - For a month: 2018-01 - For a year: 2018 For a range period:  -  Date range: 2018-01-01/2018-01-15 
        const metadata = 'metadata[Author]=John Doe&metadata[Format]=Tutorial'; // Metadata and [Dynamic Metadata](https://api.video/blog/endpoints/dynamic-metadata) filter. Send an array of key value pairs you want to filter sessios with.
        const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1
        const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25.

        // RawStatisticsListSessionsResponse
        const result = await client.rawStatistics.listVideoSessions({ videoId, period, metadata, currentPage, pageSize })
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();
# List all sessions for a video ID
import apivideo
from apivideo.apis import RawStatisticsApi
from apivideo.exceptions import ApiAuthException

api_key = "your api key here"
video_id = "your video ID here"

client = apivideo.AuthenticatedApiClient(api_key)

# If you'd rather use the sandbox environment:
# client = apivideo.AuthenticatedApiClient(api_key, production=False)

client.connect()

rawstats_api = RawStatisticsApi(client)

# Retrieve all sessions for your video ID
response = rawstats_api.list_video_sessions(video_id)
print(response)

Retrieve all sessions for a live stream

Using the unique live stream ID, you can grab details about all the different player sessions associated with a live stream. You must use api.video's player to get access to these details. If you don't want an exhaustive list of everything, you can also filter by time period. The code sample for this is:

curl --request GET \
     --url 'https://ws.api.video/analytics/live-streams/vi4k0jvEUuaTdRAEjQ4Jfrgz?period=2022-01-01T00%3A00%3A00.000Z&currentPage=1&pageSize=25' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MjQzMTkuMDk2NjY1LCJuYmYiOjE2NDI4MjQzMTkuMDk2NjY1LCJleHAiOjE2NDI4Mjc5MTkuMDk2NjY1LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.rfchf3btbMTzSukcwhUS0u4fNY4Q3g1JpoMeIz_Dls1ADmqDdKw7yBOE893C7cagb0lpuvUJvhuhgusLStsJ4nqzTveDeM2oPBQBNJjzwaJZNrImTPD4mif7Tzgxvn1_jQJA5L4gQhjd7frCIJW1yAwywrtiDPbxiWNp8fVl7r_QILjZZfslxy-kblPrHJ20Zix9VURqkGIORY5G_457nHSV9Atks1sUlt49E8b_g3jORja3MnznXBS0-0dksz2K62-QMe1_dk78V9JwbLeydqcr15M1jDLA3H6qFGI7GTsTDdZ5jKLhg5OR6yeSHFysqr3kOteTqAGdp3JuTrpZIA'
package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
    req := apivideosdk.RawStatisticsApiListLiveStreamSessionsRequest{}
    
    req.LiveStreamId("vi4k0jvEUuaTdRAEjQ4Jfrgz") // string | The unique identifier for the live stream you want to retrieve analytics for.
    req.Period("2019-01-01") // string | Period must have one of the following formats:  - For a day : \"2018-01-01\", - For a week: \"2018-W01\",  - For a month: \"2018-01\" - For a year: \"2018\" For a range period:  -  Date range: \"2018-01-01/2018-01-15\" 
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.RawStatistics.ListLiveStreamSessions(liveStreamId string, req)
    

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `RawStatistics.ListLiveStreamSessions``: %v\n", err)
    }
    // response from `ListLiveStreamSessions`: RawStatisticsListLiveStreamAnalyticsResponse
    fmt.Fprintf(os.Stdout, "Response from `RawStatistics.ListLiveStreamSessions`: %v\n", res)
}
<?php
require __DIR__ .'/vendor/autoload.php';

use Symfony\Component\HttpClient\Psr18Client;
use ApiVideo\Client\Client;
use ApiVideo\Client\Model\RawStatisticsApi;

$apiKey = 'your API key here';
$apiVideoEndpoint = 'https://ws.api.video';

$httpClient = new \Symfony\Component\HttpClient\Psr18Client();
$client = new ApiVideo\Client\Client(
    $apiVideoEndpoint,
    $apiKey,
    $httpClient
);

$rawStatistics = $client->rawStatistics()->listLiveStreamSessions('live stream ID');

print($rawStatistics);
const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const liveStreamId = 'vi4k0jvEUuaTdRAEjQ4Jfrgz'; // The unique identifier for the live stream you want to retrieve analytics for.
        const period = '2019-01-01'; // Period must have one of the following formats:  - For a day : \"2018-01-01\", - For a week: \"2018-W01\",  - For a month: \"2018-01\" - For a year: \"2018\" For a range period:  -  Date range: \"2018-01-01/2018-01-15\" 
        const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1
        const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25.

        // RawStatisticsListLiveStreamAnalyticsResponse
        const result = await client.rawStatistics.listLiveStreamSessions({ liveStreamId, period, currentPage, pageSize })
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();
# List all sessions for a live stream ID
import apivideo
from apivideo.apis import RawStatisticsApi
from apivideo.exceptions import ApiAuthException

api_key = "your api key here"
live_stream = "your live stream ID here"

client = apivideo.AuthenticatedApiClient(api_key)

# If you'd rather use the sandbox environment:
# client = apivideo.AuthenticatedApiClient(api_key, production=False)

client.connect()

rawstats_api = RawStatisticsApi(client)

# Send the request for session information
response = rawstats_api.list_live_stream_sessions(live_stream)
print(response)

Retrieve all session events

Using a session ID you retrieve from listing sessions for a video or a live stream, you can retrieve details about all the events that occurred during a session. Available event information includes:

  • type - What type of event you're dealing with, either ready, play, pause, resume, seek.backward, seek.forward or end
  • emittedAt - When the event type occurred in real time
  • at - When the event type occurred in the time line of the video if it's an event type that wouldn't have a start and stop. For example, if you pause the video, it doesn't pause for a chunk of a video, just a moment in the timeline until you start back again.
  • from - Used for an event that occurs over a chunk of time, like seek.forward, it would tell you when the viewer started fast forwarding.
  • to - Used for an event that occurs over a chunk of time, like seek.forward, it would tell you when the viewer stops fast forwarding.

The code sample looks like this:

curl --request GET \
     --url 'https://ws.api.video/analytics/sessions/psEmFwGQUAXR2lFHj5nDOpy/events?currentPage=1&pageSize=25' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI4MjQzMTkuMDk2NjY1LCJuYmYiOjE2NDI4MjQzMTkuMDk2NjY1LCJleHAiOjE2NDI4Mjc5MTkuMDk2NjY1LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.rfchf3btbMTzSukcwhUS0u4fNY4Q3g1JpoMeIz_Dls1ADmqDdKw7yBOE893C7cagb0lpuvUJvhuhgusLStsJ4nqzTveDeM2oPBQBNJjzwaJZNrImTPD4mif7Tzgxvn1_jQJA5L4gQhjd7frCIJW1yAwywrtiDPbxiWNp8fVl7r_QILjZZfslxy-kblPrHJ20Zix9VURqkGIORY5G_457nHSV9Atks1sUlt49E8b_g3jORja3MnznXBS0-0dksz2K62-QMe1_dk78V9JwbLeydqcr15M1jDLA3H6qFGI7GTsTDdZ5jKLhg5OR6yeSHFysqr3kOteTqAGdp3JuTrpZIA'
package main

import (
    "context"
    "fmt"
    "os"
    apivideosdk "github.com/apivideo/api.video-go-client"
)

func main() {
    client := apivideosdk.ClientBuilder("YOUR_API_TOKEN").Build()
    // if you rather like to use the sandbox environment:
    // client := apivideosdk.SandboxClientBuilder("YOU_SANDBOX_API_TOKEN").Build()
    req := apivideosdk.RawStatisticsApiListSessionEventsRequest{}
    
    req.SessionId("psEmFwGQUAXR2lFHj5nDOpy") // string | A unique identifier you can use to reference and track a session with.
    req.CurrentPage(int32(2)) // int32 | Choose the number of search results to return per page. Minimum value: 1 (default to 1)
    req.PageSize(int32(30)) // int32 | Results per page. Allowed values 1-100, default is 25. (default to 25)

    res, err := client.RawStatistics.ListSessionEvents(sessionId string, req)
    

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error when calling `RawStatistics.ListSessionEvents``: %v\n", err)
    }
    // response from `ListSessionEvents`: RawStatisticsListPlayerSessionEventsResponse
    fmt.Fprintf(os.Stdout, "Response from `RawStatistics.ListSessionEvents`: %v\n", res)
}
<?php
require __DIR__ .'/vendor/autoload.php';

use Symfony\Component\HttpClient\Psr18Client;
use ApiVideo\Client\Client;
use ApiVideo\Client\Model\RawStatisticsApi;

$apiKey = 'your API key';
$apiVideoEndpoint = 'https://ws.api.video';

$httpClient = new \Symfony\Component\HttpClient\Psr18Client();
$client = new ApiVideo\Client\Client(
    $apiVideoEndpoint,
    $apiKey,
    $httpClient
);

$rawStatistics = $client->rawStatistics()->listSessionEvents('session ID here');

print($rawStatistics);
const ApiVideoClient = require('@api.video/nodejs-client');

(async () => {
    try {
        const client = new ApiVideoClient({ apiKey: "YOUR_API_TOKEN" });

        const sessionId = 'psEmFwGQUAXR2lFHj5nDOpy'; // A unique identifier you can use to reference and track a session with.
        const currentPage = '2'; // Choose the number of search results to return per page. Minimum value: 1
        const pageSize = '30'; // Results per page. Allowed values 1-100, default is 25.

        // RawStatisticsListPlayerSessionEventsResponse
        const result = await client.rawStatistics.listSessionEvents({ sessionId, currentPage, pageSize })
        console.log(result);
    } catch (e) {
        console.error(e);
    }
})();
# Retrieve all details for a session by session ID
import apivideo
from apivideo.apis import RawStatisticsApi
from apivideo.exceptions import ApiAuthException

api_key = "your api key here"
session_id = "your session ID here"

client = apivideo.AuthenticatedApiClient(api_key)

# If you'd rather use the sandbox environment:
# client = apivideo.AuthenticatedApiClient(api_key, production=False)
client.connect()

rawstats_api = RawStatisticsApi(client)

# Retrieve session details
response = rawstats_api.list_session_events(session_id)
print(response)

Conclusion

With statistics you can analyze how people watch and interact with your videos and live streams.


Did this page help you?