# Video Engagement Data

{% hint style="warning" %}
Video Engagement Data API endpoints are usable only to customers with our Video add-on integrated.
{% endhint %}

## Top Video

<mark style="color:blue;">`GET`</mark> `https://api.chartbeat.com/live/video/videos/v1/`

This live API call returns the top videos on your site.

#### Query Parameters

| Name   | Type    | Description                                                                                                                                                                                                      |
| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| apikey | string  | NOTE: Your API key should no longer be set as a query param; instead, [pass it in the HTTP header](https://docs.chartbeat.com/cbp/api/real-time-apis/getting-started-with-our-real-time-api#required-parameters) |
| host   | string  | The site ID of the Site you are querying, prepended with video@ (e.g. <video@mysite.com>)                                                                                                                        |
| limit  | integer | 20 is the default limit of videos to return, but this can be increased or decreased.                                                                                                                             |

{% tabs %}
{% tab title="200 " %}

```scheme
{
    data: {
        items: [
            {
                path: "video_content_id_12345", //The path that is being passed to Chartbeat to identify the video.
                stats: {
                    visitors: 3063, //The number of people who have loaded the video.
                    watching: 2736 //The number of people who have loaded this video and are watching now
                },
                thumbnail: "https://www.mysite.com/thumbnail-11.jpg", //The URL being passed to Chartbeat for the thumbnail image.
                title: "My Great Video!" //The video title.
            },
    {
                path: "video_content_id_09876",
                stats: {
                    visitors: 1695,
                    watching: 1523
                },
                thumbnail: "https://www.mysite.com/thumbnail-22.jpg",
                title: "Must Watch: The President Said What?!"
                },
    {
                path: "video_content_id_45678",
                stats: {
                    visitors: 1588,
                    watching: 1412
                    },
                thumbnail: "https://www.mysite.com/thumbnail-33.jpg",
                title: "Our Top 10 Favorite Seinfeld Episodes"
            },
{...}            
```

{% endtab %}
{% endtabs %}

## Video Metrics

<mark style="color:blue;">`GET`</mark> `https://api.chartbeat.com/live/metrics/`

This call gives detailed information for a specific video. If no video path is specified, all metrics reflect the top results for the aggregate of all videos.

#### Query Parameters

| Name   | Type   | Description                                                                                                  |
| ------ | ------ | ------------------------------------------------------------------------------------------------------------ |
| apikey | string | Your API key.                                                                                                |
| host   | string | The site ID of the Site you are querying, prepended with video@ (e.g. <video@mysite.com>).                   |
| names  | string | Can be a comma-delineated list of any of the metrics in the table below.                                     |
| path   | string | The path that is being passed to Chartbeat to identify the video (Not the path of the page the video is on). |

{% tabs %}
{% tab title="200 Example response for call with names=video\_title,video\_duration applied as a query parameter with metrics." %}

```scheme
{
    metrics:{
        video_duration: {
                count: 13988,
                max: 11983253.3,
                sum: 2374541830.886638,
                min: 0,
                mean: 169755.6356081383
        },
        video_title:{
            count: 15242,
            unique_max: 2756,
            top:{
                My Great Movie: 463,
                Watch Now: Live With Mr News: 173,
                Poll Predicts Landslide Victory: 799,
                New Video Shows Shocking Car Chase: 164,
                Hilarious Security Footage: 222
            },
            unique: 2756,
            unique_min: 298
        }
    }
}
```

{% endtab %}
{% endtabs %}

| Optional "names" values | Metric Definitions                                                                                               |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `video_duration`        | Video length (in milliseconds)                                                                                   |
| `video_title`           | The video title                                                                                                  |
| `video_page`            | Path of the page(s) the video is on                                                                              |
| `video_host`            | Host domain of the page(s) where the video is being played                                                       |
| `video_state`           | Array of the number of visitors in different video states in the format: \[unplayed, playing, paused, completed] |