Video Analytics API

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to 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).

Sample Request

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

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

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