Video Analytics API
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
The videoAnalytics API lets you gather analytics about a video entity. The API provides the following metrics:
- Watch time
- Video views
- Video viewers
This is a unified resource to return all video related analytics. Likes and comment counts are not returned through the Video Analytics API. You can pull these counts from the Social Actions API.
Note
All API requests are represented in protocol 2.0.0 and require the header X-Restli-Protocol-Version: 2.0.0.
Permissions
| Permission | Description |
|---|---|
| r_organization_social | Retrieve organizations' posts, comments, and likes. Restricted to organizations in which the authenticated member has one of the following company page roles.
|
See Organization Access Control for more information on company page roles.
Schema
| Field Name | Type | Description |
|---|---|---|
| entity | URN | URN for the video entity with type ugcPost and includes the video. |
| type | string | Type of analytics returned:
|
| aggregation | string | Type of aggregation. One of the following:
|
| timeRange | object | The time range that the analytics will be fetched for. If missing, it will return analytics for the lifetime of the video. This parameter is optional. It is an object with fields start and end holding start and end timestamp. The time range is inclusive of the start and exclusive on the end. The start and end fields are both optional. Timestamps are in epoch format. See the sample below for how to pass this field through the API. If the video has more than ten days/weeks records, and no timeRange being passed into the API call, the aggregate_DAY and aggregate_WEEK calls will return the default 10 results. |
Retrieve Analytics Data for a Video Entity
You can retrieve analytics data for the VIEWER and VIDEO_VIEW metrics for a video entity for six months. Requests on posts older than six months do not return results.
An exception is in an instance when a video receives viral views a certain amount of time after the initial post. In this instance you can retrieve views of the video for six months after the video received the viral view.
For example, if the video received viral views two months after the initial post, results will display eight months after the post (six months after the viral view in addition to the two months after the initial post).
Sample Request
Parameters
| Name | Description | Format | Optional |
|---|---|---|---|
| q | Finder name | Value must be entity |
No |
| entity | URN for the video entity whose type should be ugcPost | URN. For example urn:li:ugcPost:6443156446455693312 |
No |
| type | The type of the analytics that will be returned | One of the following:
|
No |
| aggregation | The way to aggregate the analytics. Defaults to ALL, meaning aggregate all the data together. Analytics data for this metric will be available for six months. |
One of the following:
|
Yes. Defaults to ALL if missing. |
| timeRange | The time range that the analytics will be fetched for. If missing, it will return analytics for the lifetime of the video. | It is an object with fields start and end holding start and end timestamp. The time range is inclusive at the start and exclusive on the end. The start and end fields are both optional. Timestamps are in epoch format. If the video has more than ten days/weeks records, and no timeRange being passed into the API call, the aggregate_DAY and aggregate_WEEK calls will return the default 10 results. |
Yes |
On success, a 200 OK response returns with a list of videoAnalytics objects.
On failure, a 400 Bad Request response is returned if request parameters are not valid.
Except for value, all other fields are defined in the same way as input parameters.
timeRange is an optional field. If it is missing, it means the data is for the lifetime of the video.
- If aggregation is DAY/WEEK,
timeRangewill be start and end of the day/week (even if the data of the day is not complete). - If aggregation is
ALL, timeRange will be the timeRange from input parameter. - If input
timeRangeis missing,timeRangein output is ignored.
Sample Response
{
"elements": [
{
"entity": "urn:li:ugcPost:6426130460119830528",
"statisticsType": "VIEWER",
"timeRange": {
"end": 1535500800000,
"start": 1535414400000
},
"value": 1
},
{
"entity": "urn:li:ugcPost:6426130460119830528",
"statisticsType": "VIEWER",
"timeRange": {
"end": 1532563200000,
"start": 1532476800000
},
"value": 1
},
{
"entity": "urn:li:ugcPost:6426130460119830528",
"statisticsType": "VIEWER",
"timeRange": {
"end": 1532131200000,
"start": 1532044800000
},
"value": 1
},
{
"entity": "urn:li:ugcPost:6426130460119830528",
"statisticsType": "VIEWER",
"timeRange": {
"end": 1535760000000,
"start": 1535673600000
},
"value": 1
}
],
"paging": {
"count": 10,
"links": [],
"start": 0,
"total": 4
}
}
Response Body Fields
| Field Name | Type | Description | Guaranteed in Response? |
|---|---|---|---|
| entity | URN for the video entity whose type can be digitalmediaAsset or ugcPost which includes the video | URN string: urn:li:ugcPost:6443156446455693312 | Yes |
| type | The type of analytics that will be returned | One of the following:
|
Yes |
| value | long | Data is best effort accurate and should not be used for billing purposes | Yes |
| timeRange | The time range that the analytics will be fetched for. If missing, it will return analytics for the lifetime of the video | This parameter is optional. It is an object with fields start and end holding start and end timestamp. The time range is inclusive on the start and exclusive on the end. The start and end fields are both optional. Timestamps are in epoch format. Analytics data for this metric will be available for six months. If the video has more than ten days/weeks records, and no timeRange being passed into the API call, the aggregate_DAY and aggregate_WEEK calls will return the default 10 results. |
No |