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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.chartbeat.com/cbp/api/real-time-apis/video-engagement-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.