Video Analytics API

Artikel
10/15/2024

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. ADMINISTRATOR DIRECT_SPONSORED_CONTENT_POSTER

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: `VIDEO_VIEW` Video views with play-pause cycles for at least 3 seconds. Auto-looping videos are counted as one when loaded. Each subsequent auto-looped play does not increase this metric. Analytics data for this metric will not be available after six months. VIEWER: Unique viewers who made engaged plays on the video. Auto-looping videos are counted as one when loaded. Each subsequent auto-looped play does not increase this metric. Analytics data for this metric will not be available after six months. TIME_WATCHED: The time the video was watched in milliseconds. Video auto-looping will continue to increase this metric for each subsequent play. TIME_WATCHED_FOR_VIDEO_VIEWS: The time watched in milliseconds for video play-pause cycles that are at least 3 seconds. Video auto-looping will continue to increase this metric for each subsequent play. Analytics data for this metric will be available for six months.
aggregation	string	Type of aggregation. One of the following: `DAY`: Aggregate data on a daily basis `WEEK`: Aggregate data on a weekly basis. The week starts on Sunday and ends on Saturday `ALL` (default): Aggregate all the data together
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).

GET https://api.linkedin.com/rest/videoAnalytics?q=entity&entity=urn%3Ali%3AugcPost%3A6422171828579602432&type=TIME_WATCHED&timeRange=(start:1531165717442,end:1531770742335)&aggregation=DAY

curl -X GET https://api.linkedin.com/rest/videoAnalytics?q=entity&entity=urn%3Ali%3AugcPost%3A6422171828579602432&type=TIME_WATCHED&timeRange=(start:1531165717442,end:1531770742335)&aggregation=DAY \
-H 'Authorization: Bearer {INSERT_TOKEN}'\
-H 'LinkedIn-Version: {INSERT_VERSION}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

http
curl

GET https://api.linkedin.com/v2/videoAnalytics?q=entity&entity=urn:li:ugcPost:6422171828579602432&type=TIME_WATCHED&timeRange=(start:1531165717442,end:1531770742335)&aggregation=DAY

curl -X GET 'https://api.linkedin.com/v2/videoAnalytics?q=entity&entity=urn:li:ugcPost:6422171828579602432&type=TIME_WATCHED&timeRange=(start:1531165717442,end:1531770742335)&aggregation=DAY' \
-H 'Authorization: Bearer {INSERT_TOKEN}'

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: `VIDEO_VIEW` `VIEWER` `TIME_WATCHED` `TIME_WATCHED_FOR_VIDEO_VIEWS`	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: `DAY` `WEEK` `ALL` (default)	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, timeRange will 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 timeRange is missing, timeRange in 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: VIDEO_VIEW VIEWER TIME_WATCHED TIME_WATCHED_FOR_VIDEO_VIEWS	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

Teilen über