Ads Reporting

The LinkedIn Ads Reporting APIs provide key insights on performance such as clicks, impressions, and ad spend, and demographics information such as metrics by demographic values at the account, campaign, and creative levels. These insights help your users make the most of their LinkedIn ads experience and ensure that their campaigns are performing effectively.

Permissions

Permission Description
r_ads_reporting Retrieve reporting for advertising accounts.

If you are using legacy permissions, please refer to this page for requesting legacy permissions.

Ad Analytics

The adAnalyticsV2 endpoint supports two finder methods: Analytics and Statistics. The Analytics Finder should be used when grouping by one element(known as a pivot). The Statistics Finder should be used when grouping by two elements.

The Analytics and Statistics Finders return many of the same metrics. Some metrics returned in the Analytics Finder are not returned through the Statistics Finder. The Analytics Finder Only Fields list describes which fields are present in the Analytics Finder, but not the Statistics Finder.

An empty response is returned if there is no activity to report or if you do not have read access to the requested advertising data.

Retention

The retention period for data depends on the timeGranularity of your request and type of request.

Demographic Non-Demographic
DAILY Last 6 months Last 10 years
MONTHLY Last 2 years Last 10 years
YEARLY Last 2 years Last 10 years
ALL Last 2 years Last 10 years

Restrictions

The following restrictions apply based on your query parameters.

  • When timeGranularity=ALL, if either the start or end date of a request range is outside of the 6 month daily retention period, the dates are automatically rounded to month boundaries, and the entire month's data is included in the response. For example, if a request is made on 8/1/2017 with dateRange.start = 1/15/2017 and dateRange.end = 7/15/2017, then dateRange.start is automatically adjusted to 1/1/2017. This is because 1/15/2017 is outside of a 6 month retention period for daily data, whereas monthly data for January is still within the 2 year retention period.
  • Demographic pivots do not support carousel and video ads metrics.

Delays

Performance metrics such as metrics about a creative, campaign, or account are near real-time. Metrics based on demographics such as company size and job function may be delayed by a couple hours.

Accuracy

To protect LinkedIn member privacy, demographic metrics are approximate. To learn more about this approximation, see here.

Because metrics are approximate, you may observe minor inconsistencies when comparing:

  • Similar time ranges, for example, reporting on results over 7 days vs. 8 days
  • The sum of daily metrics to the full corresponding time period
  • Reporting levels, for example, adding campaign level data and comparing it to account level data

To minimize the effect of this approximation, select:

  • A full time period instead of adding up daily metrics for that time period
  • The highest reporting level you want to view, for example, selecting account level data instead of adding up campaign level data

Metrics Available

Field Name Type Description
actionClicks long The count of clicks on the action button of the Sponsored InMail. Sponsored InMail only.
adUnitClicks long The count of clicks on the ad unit displayed alongside the Sponsored InMail. Sponsored InMail only.
cardClicks long The number of clicks for each card of a carousel ad. The first card click of the carousel ad results in an immediate cardClick and click, whereas scrolling to other cards and clicking will count as additional cardClick.
cardImpressions long The number of impressions shown for each card of a carousel ad. The first card of the carousel ad results in an immediate cardImpression and impression, whereas scrolling to other cards will count as additional cardImpressions.
clicks long The count of chargeable clicks. Despite not charging for clicks for CPM campaigns, this field still represents those clicks for which we would otherwise charge advertisers (for example, clicks to view the landing page or company page).
commentLikes long Analytics Finder only. The count of likes of a comment. Sponsored Updates only.
comments long The count of comments. Sponsored Updates only.
companyPageClicks long The count of clicks to view the company page.
conversionValueInLocalCurrency BigDecimal Value of the conversions in the account's local currency based on rules defined by the advertiser. Conversion value is set by the advertiser at a per conversion level, and aggregated across the query time range.
costInLocalCurrency BigDecimal Cost in the account's local currency based on the pivot and timeGranularity. For example, this would be spend by member company size per month if the pivot is MEMBER_COMPANY_SIZE and timeGranularity is MONTHLY.
costInUsd BigDecimal Cost in USD based on the pivot and timeGranularity. For example, this would be spend by campaign on a given day if the pivot is CAMPAIGN and timeGranularity is DAILY.
dateRange DateRange Date range covered by the report data point. Date is specified in UTC. Start and end date are inclusive. Start date is required. End date is optional and defaults to today.
externalWebsiteConversions long, default="0" The count of conversions indicated by pixel loads on an external advertiser website.
externalWebsitePostClickConversions long, default="0" The count of post-click conversions indicated by pixel loads on an external advertiser website.
externalWebsitePostViewConversions long, default="0" The count of post-view conversions indicated by pixel loads on an external advertiser website.
follows long The count of follows. Sponsored Updates only.
fullScreenPlays long Analytics Finder only. The count of taps on the video, going into video view mode.
impressions long This is the count of "impressions" for Direct Ads and Sponsored Updates and "sends" for InMails.
landingPageClicks long The count of clicks which take the user to the creative landing page.
leadGenerationMailContactInfoShares long The number of times users shared contact info through the One Click Lead Gen for Sponsored InMail. Sponsored InMail only.
leadGenerationMailInterestedClicks long The count of InMail recipients who clicked to demonstrate interest. Sponsored InMail only.
likes long The count of likes. Sponsored Updates only.
oneClickLeadFormOpens long The count of times users opened the lead form for a One Click Lead Gen campaign.
oneClickLeads long The count of leads generated through One Click Lead Gen.
opens long The count of opens of Sponsored InMail. Sponsored InMail only.
otherEngagements long The count of user interactions with the ad unit that do not fit into any other more specific category.
pivotValues string[], default="[]" The value of the pivots for a specific record returned. For example, supplying pivots of CREATIVE and CONVERSION results in a list of records, one for each creative/conversion combination. The pivotValues contain serialized URNs for the specific creative and conversion for a record.
sends long The count of sends of Sponsored InMail. Sponsored InMail only.
shares long The count of shares. Sponsored Updates only.
textUrlClicks long The count of clicks on any links (anchor tags) that were included in the body of the Sponsored InMail. Sponsored InMail only.
totalEngagements long The count of all user interactions with the ad unit.
videoCompletions long Analytics Finder only. The count of video ads that played 97-100% of the video. This includes watches that skipped to this point if the serving location is ON_SITE.
videoFirstQuartileCompletions long Analytics Finder only. The count of video ads that played through the first quartile of the video. This includes watches that skipped to this point if the serving location is ON_SITE.
videoMidpointCompletions long Analytics Finder only. The count of video ads that played through the midpoint of the video. This includes watches that skipped to this point if the serving location is ON_SITE.
videoStarts long Analytics Finder only. The count of video ads that were started by users.
videoThirdQuartileCompletions long Analytics Finder only. The count of video ads that played through the third quartile of the video. This includes watches that skipped to this point if the serving location is ON_SITE.
videoViews long Analytics Finder only. A video ad playing for at least 2 continuous seconds 50% in-view, or a click on the CTA, whichever comes first. An interaction with the video (like going to fullscreen mode) does not count as a view.
viralCardClicks long The number of viralClicks for each card of a carousel ad. The first viralCardClick of the carousel ad results in an immediate viralCardClick and viralClick, whereas scrolling to other cards and clicking will count as additional viralCardClick.
viralCardImpressions long The number of viralImpressions shown for each card of a carousel ad. The first card of the carousel ad results in an immediate viralCardImpression and viralImpression, whereas scrolling to other cards will count as additional viralCardImpressions.
viralClicks long The count of clicks on viral impressions. See viral impressions definition. Sponsored Updates only.
viralCommentLikes long The count of likes on comments from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralComments long The count of comments from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralCompanyPageClicks long The count of clicks to view the company page from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralExternalWebsiteConversions long The count of conversions indicated by pixel loads on an external advertiser website driven by a viral event. See viral impressions definition.
viralExternalWebsitePostClickConversions long The count of post-click conversions indicated by pixel loads on an external advertiser website driven by a viral click. See viral impressions definition.
viralExternalWebsitePostViewConversions long The count of post-view conversions indicated by pixel loads on an external advertiser website driven by a viral impression. See viral impressions definition.
viralFollows long The count of follows from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralFullScreenPlays long Analytics Finder only. The count of taps on the video, going into video view mode. See viralImpressions definition.
viralImpressions long The count of viral impressions for this activity. Viral impressions are those resulting from users sharing a sponsored update to their own network of connections. Viral impressions are not counted as regular impressions. Sponsored Updates only.
viralLandingPageClicks long The count of clicks on viral impressions to take the user to the creative landing page. See viral impressions definition. Sponsored Updates only.
viralLikes long The count of likes from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralOneClickLeadFormOpens long The count of times users opened the lead form for viral impressions from a Lead Gen campaign. See viral impressions definition.
viralOneClickLeads long The count of leads generated through One Click Lead Gen from viral impressions for this activity. See viral impressions definition.
viralOtherEngagements long The count of user interactions with viral impressions that do not fit into any other more specific category. See viral impressions definition. Sponsored Updates only.
viralShares long The count of shares from viral impressions for this activity. See viral impressions definition. Sponsored Updates only.
viralTotalEngagements long The count of all user interactions with a viral ad unit. See viral impressions definition. Sponsored Updates only.
viralVideoCompletions long Analytics Finder only. The count of viral video ads that played 97-100% of the video. This includes watches that skipped to this point. See viralImpressions definition.
viralVideoFirstQuartileCompletions long Analytics Finder only. The count of viral video ads that played through the first quartile of the video. This includes watches that skipped to this point. See viralImpressions definition.
viralVideoMidpointCompletions long Analytics Finder only. The count of viral video ads that played through the midpoint of the video. This includes watches that skipped to this point. See viralImpressions definition.
viralVideoStarts long Analytics Finder only. The count of viral video ads that were started by users. See viralImpressions definition. Since viral videos are automatically played for ON_SITE, this will be the same as viralImpressions if the servingLocation is ON_SITE.
viralVideoThirdQuartileCompletions long Analytics Finder only. The count of viral video ads that played through the third quartile of the video. This includes watches that skipped to this point. See viralImpressions definition
viralVideoViews long Analytics Finder only. A viral video ad playing for at least 2 continuous seconds 50% in-view, or a click on the CTA, whichever comes first. An interaction with the video (like going to full screen mode) does not count as a view. See viralImpressions definition.

Analytics Finder Only Fields

Note that the following fields are present in the Analytics Finder, but not the Statistics Finder:

  • commentLikes
  • fullScreenPlays
  • videoCompletions
  • videoFirstQuartileCompletions
  • videoMidpointCompletions
  • videoStarts
  • videoThirdQuartileCompletions
  • videoViews
  • viralFullScreenPlays
  • viralVideoCompletions
  • viralVideoFirstQuartileCompletions
  • viralVideoMidpointCompletions
  • viralVideoStarts
  • viralVideoThirdQuartileCompletions
  • viralVideoViews

Analytics Finder

The Analytics Finder should be used when specifying a single pivot. This finder also has the most comprehensive set of fields returned.

GET https://api.linkedin.com/v2/adAnalyticsV2?q=analytics&pivot={pivot}&timeGranularity={time}

Query Parameters

Parameter Description Format Required
q Designates the query finder. Must be analytics for the Analytics Finder. String Yes
pivot Pivot of results, by which each report data point is grouped. The following enum values are supported:
  • COMPANY - Group results by advertiser's company.
  • ACCOUNT - Group results by account.
  • SHARE - Group results by sponsored share.
  • CAMPAIGN - Group results by campaign.
  • CREATIVE - Group results by creative.
  • CAMPAIGN_GROUP - Group results by campaign group.
  • CONVERSION - Group results by conversion.
  • SERVING_LOCATION - Group results by serving location, onsite or offsite.
  • CARD_INDEX - Group results by the index of where a card appears in a carousel ad creative. Metrics are based on the index of the card at the time when the user's action (impression, click, etc.) happened on the creative (Carousel creatives only).
  • MEMBER_COMPANY_SIZE - Group results by member company size.
  • MEMBER_INDUSTRY - Group results by member industry.
  • MEMBER_SENIORITY - Group results by member seniority.
  • MEMBER_JOB_TITLE - Group results by member job title.
  • MEMBER_JOB_FUNCTION - Group results by member job function.
  • MEMBER_COUNTRY - Group results by member country.
  • MEMBER_REGION - Group results by member region.
  • MEMBER_COMPANY - Group results by member company.
String Yes
dateRange.start Represents the inclusive start time range of the analytics. If unset, it indicates an open range up to the end time. Date object Yes
dateRange.end Represents the inclusive end time range of the analytics. Must be after start time if it's present. If unset, it indicates an open range from start time to everything after. Date object No
timeGranularity Time granularity of results. Valid enum values:
  • ALL - Results grouped into a single result across the entire time range of the report.
  • DAILY - Results grouped by day.
  • MONTHLY - Results grouped by month.
  • YEARLY - Results grouped by year.
String Yes
campaignType Match result by a campaign type. Supported types are [TEXT_AD, SPONSORED_UPDATES, SPONSORED_INMAILS, DYNAMIC]. Requires at least one other facet. Defaults to empty. Array of Campaign Type Values No
shares Match result by share facets. Defaults to empty. Array of Share URN Yes unless another facet is provided.
campaigns Match result by campaign facets. Defaults to empty. Array of Sponsored Campaign URN Yes unless another facet is provided.
creatives Match result by creative facets. Defaults to empty. Array of Sponsored Creative URN Yes unless another facet is provided.
campaignGroups Match result by campaign group facets. Defaults to empty. Array of Campaign Group URN Yes unless another facet is provided.
accounts Match result by sponsored ad account facets. Defaults to empty. Array of Account URN Yes unless another facet is provided.
companies Match result by company facets. Defaults to empty. Array of Organization URN Yes unless another facet is provided.

Sample Request

The following sample gets analytics for a particular campaign beginning in 2017.

GET https://api.linkedin.com/v2/adAnalyticsV2?q=analytics&pivot=CAMPAIGN&dateRange.start.day=1&dateRange.start.month=1&dateRange.start.year=2017&timeGranularity=DAILY&campaigns[0]=urn:li:sponsoredCampaign:1234567

Sample Response

{
    "elements": [
        {
            "actionClicks": 0,
            "adUnitClicks": 0,
            "clicks": 177,
            "comments": 0,
            "companyPageClicks": 15,
            "conversionValueInLocalCurrency": "0.0",
            "costInLocalCurrency": "244.85000",
            "costInUsd": "244.85000",
            "dateRange": {
                "end": {
                    "day": 20,
                    "month": 3,
                    "year": 2018
                },
                "start": {
                    "day": 12,
                    "month": 10,
                    "year": 2017
                }
            },
            "externalWebsiteConversions": 0,
            "externalWebsitePostClickConversions": 0,
            "externalWebsitePostViewConversions": 0,
            "follows": 0,
            "fullScreenPlays": 0,
            "impressions": 54494,
            "landingPageClicks": 67,
            "leadGenerationMailContactInfoShares": 0,
            "leadGenerationMailInterestedClicks": 0,
            "likes": 8,
            "oneClickLeadFormOpens": 0,
            "oneClickLeads": 0,
            "opens": 0,
            "otherEngagements": 1,
            "pivot": "CAMPAIGN",
            "pivotValue": "urn:li:sponsoredCampaign:134704654",
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ],
            "shares": 0,
            "textUrlClicks": 0,
            "totalEngagements": 186,
            "videoCompletions": 0,
            "videoFirstQuartileCompletions": 0,
            "videoMidpointCompletions": 0,
            "videoStarts": 0,
            "videoThirdQuartileCompletions": 0,
            "videoViews": 0,
            "viralClicks": 0,
            "viralComments": 0,
            "viralCompanyPageClicks": 0,
            "viralExternalWebsiteConversions": 0,
            "viralExternalWebsitePostClickConversions": 0,
            "viralExternalWebsitePostViewConversions": 0,
            "viralFollows": 0,
            "viralFullScreenPlays": 0,
            "viralImpressions": 86,
            "viralLandingPageClicks": 0,
            "viralLikes": 0,
            "viralOneClickLeadFormOpens": 0,
            "viralOneClickLeads": 0,
            "viralOtherEngagements": 0,
            "viralShares": 0,
            "viralTotalEngagements": 0,
            "viralVideoCompletions": 0,
            "viralVideoFirstQuartileCompletions": 0,
            "viralVideoMidpointCompletions": 0,
            "viralVideoStarts": 0,
            "viralVideoThirdQuartileCompletions": 0,
            "viralVideoViews": 0
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Note

We currently do not support queries to get analytics for deleted shares that were promoted as Sponsored Content. As creatives for Sponsored Content reference a particular share, you can retrieve analytics for the deleted share by requesting analytics for the creatives that sponsored the deleted share.

Statistics Finder

The Statistics Finder can be used when specifying up to two pivots. This finder returns fewer fields than the Analytics Finder. Refer to the Analytics Finder Only Fields list for the list of fields the Analytics Finder returns that are not returned through the Statistics Finder.

GET https://api.linkedin.com/v2/adAnalyticsV2?q=statistics&pivots[0]={pivot}&timeGranularity={time}

Query Parameters

Parameter Description Format Required
q Designates the query finder. Must be statistics for the Statistics Finder. String Yes
pivots Pivot of results, by which each report data point is grouped. Accepts up to 2 values. The following enum values are supported:
  • COMPANY - Group results by advertiser's company.
  • ACCOUNT - Group results by account.
  • SHARE - Group results by sponsored share.
  • CAMPAIGN - Group results by campaign.
  • CREATIVE - Group results by creative.
  • CAMPAIGN_GROUP - Group results by campaign group.
  • CONVERSION - Group results by conversion.
  • SERVING_LOCATION - Group results by serving location, onsite or offsite.
  • CARD_INDEX - Group results by the index of where a card appears in a carousel ad creative. Metrics are based on the index of the card at the time when the user's action (impression, click, etc.) happened on the creative (Carousel creatives only).
Array of Strings Yes
dateRange.start Represents the inclusive start time range of the analytics. If unset, it indicates an open range up to the end time. Date object Yes
dateRange.end Represents the inclusive end time range of the analytics. Must be after start time if it's present. If unset, it indicates an open range from start time to everything after. Date object No
objectiveType Filters results by objective type. The following enum values are supported:
  • LEAD_GENERATION
  • CREATIVE_ENGAGEMENT
  • WEBSITE_TRAFFIC
  • VIDEO_VIEW
  • BRAND_AWARENESS
  • WEBSITE_CONVERSION
  • WEBSITE_VISIT
  • ENGAGEMENT
  • JOB_APPLICANT
String No
timeGranularity Time granularity of results. Valid enum values:
  • ALL - Results grouped into a single result across the entire time range of the report.
  • DAILY - Results grouped by day.
  • MONTHLY - Results grouped by month.
  • YEARLY - Results grouped by year.
String Yes
campaignType Match result by a campaign type. Supported types are [TEXT_AD, SPONSORED_UPDATES, SPONSORED_INMAILS, DYNAMIC]. Requires at least one other facet. Defaults to empty. Array of Campaign Type Values No
shares Match result by share facets. Defaults to empty. Array of Share URN Yes unless another facet is provided.
campaigns Match result by campaign facets. Defaults to empty. Array of Sponsored Campaign URN Yes unless another facet is provided.
creatives Match result by creative facets. Defaults to empty. Array of Sponsored Creative URN Yes unless another facet is provided.
campaignGroups Match result by campaign group facets. Defaults to empty. Array of Campaign Group URN Yes unless another facet is provided.
accounts Match result by sponsored ad account facets. Defaults to empty. Array of Account URN Yes unless another facet is provided.
companies Match result by company facets. Defaults to empty. Array of Organization URN Yes unless another facet is provided.

Sample Request

The following sample gets statistics for a particular campaign beginning in 2017.

GET https://api.linkedin.com/v2/adAnalyticsV2?q=statistics&pivots[0]=CAMPAIGN&dateRange.start.day=1&dateRange.start.month=1&dateRange.start.year=2017&timeGranularity=DAILY&campaigns[0]=urn:li:sponsoredCampaign:1234567

Sample Response

{
    "elements": [
        {
            "actionClicks": 0,
            "adUnitClicks": 0,
            "clicks": 177,
            "comments": 0,
            "companyPageClicks": 15,
            "conversionValueInLocalCurrency": "0.0",
            "costInLocalCurrency": "244.85000",
            "costInUsd": "244.85000",
            "dateRange": {
                "end": {
                    "day": 20,
                    "month": 3,
                    "year": 2018
                },
                "start": {
                    "day": 12,
                    "month": 10,
                    "year": 2017
                }
            },
            "externalWebsiteConversions": 0,
            "externalWebsitePostClickConversions": 0,
            "externalWebsitePostViewConversions": 0,
            "follows": 0,
            "impressions": 54494,
            "landingPageClicks": 67,
            "leadGenerationMailContactInfoShares": 0,
            "leadGenerationMailInterestedClicks": 0,
            "likes": 8,
            "oneClickLeadFormOpens": 0,
            "oneClickLeads": 0,
            "opens": 0,
            "otherEngagements": 1,
            "pivot": "CAMPAIGN",
            "pivotValue": "urn:li:sponsoredCampaign:134704654",
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ],
            "shares": 0,
            "textUrlClicks": 0,
            "totalEngagements": 186,
            "viralClicks": 0,
            "viralComments": 0,
            "viralCompanyPageClicks": 0,
            "viralExternalWebsiteConversions": 0,
            "viralExternalWebsitePostClickConversions": 0,
            "viralExternalWebsitePostViewConversions": 0,
            "viralFollows": 0,
            "viralImpressions": 86,
            "viralLandingPageClicks": 0,
            "viralLikes": 0,
            "viralOneClickLeadFormOpens": 0,
            "viralOneClickLeads": 0,
            "viralOtherEngagements": 0,
            "viralShares": 0,
            "viralTotalEngagements": 0
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}