Reporting

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 LinkedIn 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.

Ad Analytics

The adAnalytics 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 up to three elements.

The adAnalytics endpoint does not support pagination.

Some metrics are not available with demographics pivots. These are noted in the metric descriptions below.

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.

Requests to adAnalytics may have a long list of params causing them to exceed max request URL lengths. If you encounter a 414 error or expect to have long request URLs, refer to the query tunneling guide for how to adjust your calls.

Retention

The retention period for data depends on the type of request. Requests for performance data (e.g. by account, campaign, creative, etc.) is ten (10) years. The retention for demographics data (e.g. by member title, job function, seniority, etc.) is two (2) years.

Restrictions

The following restrictions apply based on your query parameters.

• 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.
• Pagination is not supported.
• Some metrics are not available with specific pivots (e.g. conversion or demographics pivots). These are noted in the metric descriptions below.
• 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/2021 with dateRange.start = 1/15/2021 and dateRange.end = 7/15/2021, then dateRange.start is automatically adjusted to 1/1/2021. This is because 1/15/2021 is outside of a 6 month retention period for daily data, whereas monthly data for January is still within the 2 year retention period.
• Response is limited to 15,000 elements.
• Demographic pivots only support the top 100 demographic values for each creative for each day. For example, if a creative is shown to members with 1000 different titles, a query for the impressions for that creative with a MEMBER_JOB_TITLE pivot will only return the 100 titles with the most impressions for that creative for that day.
• Demographic values will not be returned for ads receiving engagement from too few members.
• Demographic pivots have a minimum threshold of 3 events. Demographic values with less than 3 events will be dropped from the query results.
• Demographic pivots do not support carousel metrics.

Delays

Performance metrics such as metrics about a creative, campaign, or account are near real-time. Metrics based on any member demographics such as company size and job function may be delayed by 12 to 24 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

Non-Targeted Companies

Analytics can be pivoted by company name to organize results by company name and understand which companies saw a campaign or ad creative. These results may include companies that were not targeted in a campaign even if the advertiser explicitly targeted specific companies to see their campaign. This is possible due to any of the following reasons:

1. LinkedIn members who work at more than one company
2. LinkedIn members who switch jobs during the campaign's duration
3. Audience expansion is turned on
4. Targeted companies are parent companies of other companies
5. Advertiser changed the companies targeted during the campaign

Metrics Available

Field Name	Type	Description
actionClicks	long	The count of clicks on the action button of the Sponsored Messaging ad.
adUnitClicks	long	The count of clicks on the ad unit displayed alongside the Sponsored Messaging ad.
approximateMemberReach	long	The estimated number of unique member accounts with at least one impression. This metric is an updated and more accurate version of legacy metric approximateUniqueImpressions. This metric is only available when the number of days in the date range is less than or equal to 92 days. This metric will be fully launched in Jan 2024.
cardClicks	long	Non-demographic pivots only. 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	Non-demographic pivots only. 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 based on objective (for example, clicks to view the landing page or company page).
commentLikes	long	The count of likes of a comment. Sponsored Content only.
comments	long	The count of comments. Sponsored Content only.
companyPageClicks	long	The count of clicks to view the company page.
conversionValueInLocalCurrency	BigDecimal	Non-demographic pivots only. 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. Cost is not adjusted for over delivery when a member demographic pivot is specified in the request.
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. Cost is not adjusted for over delivery when a member demographic pivot is specified in the request.
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.
documentCompletions	long	The number of times users reached 100% of the document’s length, including those that skipped to this point. This metric is only available for document ads and not all dimensions.
documentFirstQuartileCompletions	long	The number of times users reached the first quartile of the document’s length, including those that skipped to this point. This metric is only available for document ads and not all dimensions.
documentMidpointCompletions	long	The number of times users reached the second quartile of the document’s length, including those that skipped to this point. This metric is only available for document ads and not all dimensions.
documentThirdQuartileCompletions	long	The number of times users reached the third quartile of the document’s length, including those that skipped to this point. This metric is only available for document ads and not all dimensions.
downloadClicks	long	The number of times users have indicated the intent to download the media in an ad by clicking the download icon. This may or may not result in an actual download (e.g. if the user rejects a browser download prompt). This metric is only available for ad formats supporting media downloads.
externalWebsiteConversions	long, default="0"	Total number of times users took a desired action after clicking on or seeing your ad. When conversions cannot be attributed to individual users, group level attribution or estimation may be used.
externalWebsitePostClickConversions	long, default="0"	Total number of times users took a desired action after clicking on your ad. When conversions cannot be attributed to individual users, group level attribution or estimation may be used.
externalWebsitePostViewConversions	long, default="0"	Total number of times users took a desired action after seeing your ad. When conversions cannot be attributed to individual users, group level attribution or estimation may be used.
follows	long	The count of follows. Sponsored Content and Follower ads only.
fullScreenPlays	long	Number of times members click on the full screen button or on the video(mobile only) to go into full screen mode.
headlineClicks	long	The number of times members clicked on the headline of conversation ads.
headlineImpressions	long	The number of times members were shown the headline of conversation ads.
impressions	long	This is the count of "impressions" for Sponsored Content and "sends" for Sponsored Messaging.
jobApplications	BigDecimal	The number of times a member completed a job application after viewing or clicking on an ad. Currently, this metric is broken down into postViewJobApplications (if the member applied after viewing the ad) and postClickJobApplications (if the member applied after clicking the ad).
jobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after viewing or clicking on an ad which has a LinkedIn job landing page. Currently, this metric is broken down into postViewJobApplyClicks (if the member performed the action after viewing the ad) and postClickJobApplyClicks (if the member performed the action after clicking the ad).
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 Messaging ads.
leadGenerationMailInterestedClicks	long	The count of Sponsored Messaging ad recipients who clicked to demonstrate interest.
likes	long	The count of likes. Sponsored Content 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 Messaging ads.
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. To resolve these URNs to their corresponding entities, refer to LinkedIn Marketing API URN Resolution.
postClickJobApplications	BigDecimal	The number of times a member completed a job application after clicking on an ad. See also 'jobApplications'.
postClickJobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after clicking on an ad which has a LinkedIn job landing page. See also 'jobApplyClicks'.
postClickRegistrations	BigDecimal	The number of times a member has registered for an event or seminar after clicking on an ad which has a LinkedIn landing page. This includes gross registrations and does not account for a user unregistering.
postViewJobApplications	BigDecimal	The number of times a member completed a job application after viewing an ad. See also 'jobApplications'.
postViewJobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after clicking an ad which has a LinkedIn job landing page. See also 'jobApplyClicks'.
postViewRegistrations	BigDecimal	The number of times a member has registered for an event or seminar after viewing an ad which has a LinkedIn event landing page. This includes gross registrations and does not account for a user unregistering. See also 'registrations'.
reactions	long	The count of positive reactions on Sponsored Content which can capture, like, interest, praise, and other responses.
registrations	BigDecimal	The number of times a member has registered for an event or seminar after viewing or clicking on an ad which has a LinkedIn event landing page. This includes gross registrations and does not account for a user unregistering.
sends	long	The count of sends of Sponsored Messaging ads.
shares	long	The count of shares. Sponsored Content only.
talentLeads	long	Number of leads captured through a talent media campaign.
textUrlClicks	long	The count of clicks on any links (anchor tags) that were included in the body of the Sponsored Messaging ad.
totalEngagements	long	The count of all user interactions with the ad unit.
validWorkEmailLeads	long	The count of leads with a valid work email that does not use an established free or personal email domain.
videoCompletions	long	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	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	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	The count of video ads that were started by users.
videoThirdQuartileCompletions	long	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	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	Non-demographic pivots only. 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	Non-demographic pivots only. 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 Content only.
viralCommentLikes	long	The count of likes on comments from viral impressions for this activity. See viral impressions definition. Sponsored Content only.
viralComments	long	The count of comments from viral impressions for this activity. See viral impressions definition. Sponsored Content only.
viralCompanyPageClicks	long	The count of clicks to view the company page from viral impressions for this activity. See viral impressions definition. Sponsored Content only.
viralDocumentCompletions	long	The number of times users reached 100% of the document’s length on a viral post, including those that skipped to this point. This metric is only available for document ads.
viralDocumentFirstQuartileCompletions	long	The number of times users reached the first quartile of the document’s length on a viral post, including those that skipped to this point. This metric is only available for document ads.
viralDocumentMidpointCompletions	long	The number of times users reached the second quartile of the document’s length on a viral post, including those that skipped to this point. This metric is only available for document ads.
viralDocumentThirdQuartileCompletions	long	The number of times users reached the third quartile of the document’s length on a viral post, including those that skipped to this point. This metric is only available for document ads.
viralDownloadClicks	long	The number of times users have indicated the intent to download the media in a viral ad by clicking the download icon. This may or may not result in an actual download (e.g. if the user rejects a browser download prompt). Only available for ads supporting media downloads.
viralExternalWebsiteConversions	long	The count of conversions that are attributed to your ads driven by a viral event. See viral impressions definition.
viralExternalWebsitePostClickConversions	long	The count of post-click conversions that are attributed to your ads driven by a viral click. See viral impressions definition.
viralExternalWebsitePostViewConversions	long	The count of post-view conversions that are attributed to your ads 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 Content only.
viralFullScreenPlays	long	Number of times members click on the full screen button or on the video(mobile only) to go into full screen mode. See viralImpressions definition.
viralImpressions	long	The count of viral impressions for this activity. Viral impressions are those resulting from users sharing sponsored content to their own network of connections. Viral impressions are not counted as regular impressions. Sponsored Content only.
viralJobApplications	BigDecimal	The number of times a member completed a job application after viewing or clicking on a viral ad. Currently, this metric is broken down into viralPostViewJobApplications (if the member performed the action after viewing the viral ad) and viralPostClickJobApplications (if the member performed the action after clicking the viral ad).
viralJobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after viewing or clicking on a viral ad which has a LinkedIn job landing page during the date range.Currently, this metric is broken down into viralPostViewJobApplyClicks (if the member performed the action after viewing the viral ad) and viralPostClickJobApplyClicks (if the member performed the action after clicking the viral ad).
viralLandingPageClicks	long	The count of clicks on viral impressions to take the user to the creative landing page. See viral impressions definition. Sponsored Content only.
viralLikes	long	The count of likes from viral impressions for this activity. See viral impressions definition. Sponsored Content 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 Content only.
viralPostClickJobApplications	BigDecimal	The number of times a member completed a job application after clicking on a viral ad.
viralPostClickJobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after clicking on a viral ad which has a LinkedIn job landing page.
viralPostClickRegistrations	BigDecimal	The number of times a member has registered for an event or seminar after clicking on a viral ad which has a LinkedIn landing page. See viralImpressions definition. This includes gross registrations and does not account for a user unregistering.
viralPostViewJobApplications	BigDecimal	The number of times a member completed a job application after viewing a viral ad.
viralPostViewJobApplyClicks	BigDecimal	The number of times a member clicked on the job’s apply button on an LinkedIn jobs page after viewing a viral ad which has a LinkedIn job landing page.
viralPostViewRegistrations	BigDecimal	The number of times a member has registered for an event or seminar after viewing a viral ad which has a LinkedIn event landing page. See viralImpressions definition. This includes gross registrations and does not account for a user unregistering.
viralReactions	long	The count of positive reactions on viral Sponsored Content which can capture like, interest, praise, and other responses. See viral impressions definition for details on viral engagements.
viralRegistrations	BigDecimal	The number of times a member has registered for an event or seminar after viewing or clicking on a viral ad which has a LinkedIn event landing page. See viralImpressions definition. This includes gross registrations and does not account for a user unregistering.
viralShares	long	The count of shares from viral impressions for this activity. See viral impressions definition. Sponsored Content only.
viralTotalEngagements	long	The count of all user interactions with a viral ad unit. See viral impressions definition. Sponsored Content only.
viralVideoCompletions	long	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	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	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	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	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	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.

Demographic Pivot Fields Restrictions

The following fields are present only for non-demographic pivots

• conversionValueInLocalCurrency
• cardImpressions
• cardClicks
• viralCardImpressions
• viralCardClicks

Analytics Finder

The Analytics Finder should be used when specifying a single pivot.

http

GET https://api.linkedin.com/rest/adAnalytics?q=analytics&pivot={pivot}&timeGranularity={time}&dateRange={dateRange}&{facet}=List({URN_1},{URN_2})

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?q=analytics&pivot=CREATIVE&timeGranularity=DAILY&dateRange={dateRange}&{facet}=List({URN_1},{URN_2})' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Query Parameters

Parameter	Description	Format	Required
q	Designates the query finder. Must be analytics for the Analytics Finder.	String	Yes
pivot.value	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. CONVERSATION_NODE - The element row in the conversation will be the information for each individual node of the conversation tree. CONVERSATION_NODE_OPTION_INDEX - Used actionClicks are deaggregated and reported at the Node Button level. The second value of the pivot_values will be the index of the button in the node. SERVING_LOCATION - Group results by serving location, onsite or offsite. UNKNOWN means the serving location cannot be determined, which can result from metrics produced by machine learning models. 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_V2 - Group results by member country. MEMBER_REGION_V2 - Group results by member region. MEMBER_COMPANY - Group results by member company. PLACEMENT_NAME - Group results by placement. UNKNOWN means the placement cannot be determined, which can result from metrics produced by machine learning models. IMPRESSION_DEVICE_TYPE - Group results by the device type the ad made an impression on. Reach metrics and conversion metrics will not be available when this pivot is used.	String	No
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.value	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.value	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.	String	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.
sortBy.field	The field by which the results are sorted. Supported values include: COST_IN_LOCAL_CURRENCY IMPRESSIONS CLICKS ONE_CLICK_LEADS OPENS SENDS EXTERNAL_WEBSITE_CONVERSIONS	String	Yes if sortBy.order is provided.
sortBy.order	The order of the results. Supported values include: ASCENDING DESCENDING	String	Yes if sortBy.field is provided.

Sample Request

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

http

GET https://api.linkedin.com/rest/adAnalytics?q=analytics&pivot=CREATIVE&timeGranularity=DAILY&dateRange=(start:(year:2021,month:1,day:1))&campaigns=List(urn%3Ali%3AsponsoredCampaign%3A1234567)

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?q=analytics&pivot=CREATIVE&timeGranularity=DAILY&dateRange=(start:(year:2021,month:1,day:1))&campaigns=List(urn%3Ali%3AsponsoredCampaign%3A1234567)' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Sample Response

{
    "elements": [
        {
            "actionClicks": 0,
            "adUnitClicks": 0,
            "clicks": 177,
            "costInLocalCurrency": "244.85000",
            "costInUsd": "244.85000",
            "dateRange": {
                "end": {
                    "day": 20,
                    "month": 3,
                    "year": 2021
                },
                "start": {
                    "day": 12,
                    "month": 10,
                    "year": 2020
                }
            },
            "externalWebsiteConversions": 0,
            "impressions": 54494,
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ],
            "videoStarts": 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.
• To retrieve analytics data on a video entity, you can refer to the Video Analytics API

Requesting Specific Metrics in the Analytics Finder

When using pivots in the adAnalytics endpoint with projection and response decoration, the finder sometimes generates errors, including 400 or 500, indicating too much data is being called.

As of September 30, 2020, LinkedIn requires you to issue specific metrics in a request, using the fields parameter. You can request up to 20 metrics.

Please note that the projection parameter is not sufficient to fix errors related to too much data requested.

In the sample below, the fields parameter specifies a limited set of metrics.

• externalWebsiteConversions
• dateRange
• impressions
• landingPageClicks
• likes
• shares
• costInLocalCurrency
• approximateUniqueImpressions
• pivotValues

Note that each metric is separated by a comma after the fields= keyword.

http

GET https://api.linkedin.com/rest/adAnalytics?q=analytics&dateRange=(start:(year:2019,month:5,day:28),end:(year:2019,month:9,day:30))&timeGranularity=DAILY&accounts=List(urn%3Ali%3AsponsoredAccount%3A502840441)&pivot=MEMBER_COMPANY&projection=(*,elements*(externalWebsiteConversions,dateRange(*),impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValues*~(localizedName)))&fields=externalWebsiteConversions,dateRange,impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValues

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?q=analytics&dateRange=(start:(year:2019,month:5,day:28),end:(year:2019,month:9,day:30))&timeGranularity=DAILY&accounts=List(urn%3Ali%3AsponsoredAccount%3A502840441)&pivot=MEMBER_COMPANY&projection=(*,elements*(externalWebsiteConversions,dateRange(*),impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValues*~(localizedName)))&fields=externalWebsiteConversions,dateRange,impressions,landingPageClicks,likes,shares,costInLocalCurrency,approximateUniqueImpressions,pivotValues' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Sample Response

{ "elements": [
        {
            "pivotValues": [ 
                   "urn:li:organization:1111" 
             ] ,
            "dateRange": {
                "start": {
                    "month": 5,
                    "year": 2019,
                    "day": 28
                },
                "end": {
                    "month": 5,
                    "year": 2019,
                    "day": 28
                }
            },
            "landingPageClicks": 0,
            "costInLocalCurrency": "0.0",
            "impressions": 6,
            "shares": 0,
            "approximateUniqueImpressions": 2,
            "externalWebsiteConversions": 0, 
            "pivotValues~": [
                   {
                          "localizedName": "ACME"
                   }
            ],
            "likes": 0
        },
        {
             "pivotValues": [ 
                   "urn:li:organization:1111" 
             ] ,
            "dateRange": {
                "start": {
                    "month": 5,
                    "year": 2019,
                    "day": 29
                },
                "end": {
                    "month": 5,
                    "year": 2019,
                    "day": 29
                }
            },
            "landingPageClicks": 11,
            "costInLocalCurrency": "19.91833",
            "impressions": 165,
            "shares": 0,
            "approximateUniqueImpressions": 52,
            "externalWebsiteConversions": 0,
            "pivotValues~": [
                {
                    "localizedName": "ACME"
                }
            ],
            "likes": 0
        }]}

For detail on using Field Projections, refer to Field Projections.

Data Throttling

As of August 31, 2020, LinkedIn is setting an upper bound on the data that can be requested in a short window of time from this endpoint. LinkedIn will start throttling the requests from an application that exceeds the upper limit of data that can be returned in a 5 min window. In order to reduce the data load on each request we encourage you to use field parameters as specified above in Requesting Specific Fields in the Analytics Finder section.

Data limit for all queries over a 5 min interval: 45 million metric values(where metric value is the value for a metric specified in the fields parameter).

Example of data limit computation for the above request/response:

• Metrics requested: 9
• Number of records returned: 2 (1 per day)
• Total data cost of query: 9 *2 = 18 metrics values

Statistics Finder

The Statistics Finder can be used when specifying up to three pivots.

As of September 30, 2020, LinkedIn requires you to issue specific metrics in a request, using the fields parameter. You can request up to 20 metrics. For an example of a request that calls specific metrics, see Requesting Specific Fields in the Analytics Finder

http

GET https://api.linkedin.com/rest/adAnalytics?q=statistics&pivots=List({pivot_1},{pivot_2},{pivot_3})&timeGranularity={time}&{facet}=List({URN_1},{URN_2})

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?q=statistics&pivots=List({pivot_1},{pivot_2},{pivot_3})&timeGranularity={time}&{facet}=List({URN_1},{URN_2})' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Query Parameters

Parameter	Description	Format	Required
q	Designates the query finder. Must be statistics for the Statistics Finder.	String	Yes
pivots.value	Pivot of results, by which each report data point is grouped. Accepts up to 3 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. CONVERSATION_NODE - The element row in the conversation will be the information for each individual node of the conversation tree. CONVERSATION_NODE_OPTION_INDEX - Used actionClicks are deaggregated and reported at the Node Button level. The second value of the pivot_values will be the index of the button in the node. SERVING_LOCATION - Group results by serving location, onsite or offsite. UNKNOWN means the serving location cannot be determined, which can result from metrics produced by machine learning models. OBJECTIVE_TYPE: Group results by campaign's objective type. 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). PLACEMENT_NAME - Group results by placement. UNKNOWN means the placement cannot be determined, which can result from metrics produced by machine learning models. IMPRESSION_DEVICE_TYPE - Group results by the device type the ad made an impression on. Reach metrics and conversion metrics will not be available when this pivot is used.	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.value	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.value	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.value	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.	String	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.
sortBy.field	The field by which the results are sorted. Supported values include: COST_IN_LOCAL_CURRENCY IMPRESSIONS CLICKS ONE_CLICK_LEADS OPENS SENDS EXTERNAL_WEBSITE_CONVERSIONS	String	Yes if sortBy.order is provided.
sortBy.order	The order of the results. Supported values include: ASCENDING DESCENDING	String	Yes if sortBy.field is provided.

Sample Request

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

http

GET https://api.linkedin.com/rest/adAnalytics?q=statistics&pivots=List(CAMPAIGN)&dateRange=(start:(year:2021,month:1,day:1))&timeGranularity=DAILY&campaigns=List(urn:li:sponsoredCampaign:1234567)

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?q=statistics&pivots=List(CAMPAIGN)&dateRange=(start:(year:2021,month:1,day:1))&timeGranularity=DAILY&campaigns=List(urn:li:sponsoredCampaign:1234567)' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Sample Response

{
    "elements": [
        {
            "actionClicks": 0,
            "adUnitClicks": 0,
            "clicks": 177,
            "costInLocalCurrency": "244.85000",
            "costInUsd": "244.85000",
            "dateRange": {
                "end": {
                    "day": 20,
                    "month": 3,
                    "year": 2021
                },
                "start": {
                    "day": 12,
                    "month": 10,
                    "year": 2020
                }
            },
            "externalWebsiteConversions": 0,
            "impressions": 54494,
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ],
            "totalEngagements": 186
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Handling Pivot Errors

When trying to use pivots in the adAnalytics endpoint with projection and response decoration, errors sometimes occur when too much data is called. If you receive a 400 or 500 error because of handling too much data, consider the following. Understanding Requesting Specific Metrics in the Analytics Finder can help.

Reporting Microsoft Bing Locations

The LMS Ad reporting mechanism now uses the Microsoft Bing location dataset. In addition to targeting, the adAnalystics endpoint adds new demographic pivots for Bing location information for the following demographic categories:

• MEMBER_COUNTRY_V2
• MEMBER_REGION_V2
• MEMBER_COUNTY

Note

All use of the Microsoft Bing Maps location data is subject to Microsoft Bing Maps and MapPoint Web Service End User Terms of Use and Embedded Maps Service Terms of Use and the Microsoft Privacy Statement. By accessing any Microsoft Bing Maps location data, you are agreeing to be bound by these Microsoft terms.

Sample Requests

Member Country

http

GET https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=(MEMBER_COUNTRY_V2)&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=(MEMBER_COUNTRY_V2)&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Sample Response

{ 
   "elements":[ 
      { 
         "pivotValues": [
           "urn:li:geo:1"
         ],
         "impressions":29
      },
      { 
         "pivotValues": [
           "urn:li:geo:2"
         ],
         "impressions":28
      },
      { 
         "pivotValues": [
           "urn:li:geo:3"
         ],
         "impressions":28
      }
   ],
   "paging":{ 
      "count":10,
      "start":0,
      "links":[ 
         { 
            "rel":"next",
            "href":"/adAnalytics?q=analytics&timeGranularity.value=ALL&dateRange=(start:(day:28,month:7,year:2019))&start=10&count=10&pivot.value=_MEMBER_COUNTRY_V2&accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&fields=impressions,pivotValues",
            "type":"application/json"
         }
      ]
   }
}

Member Region

http

GET https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=MEMBER_REGION_V2&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=MEMBER_REGION_V2&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

---

Sample Response

{ 
   "elements":[ 
      { 
         "pivotValues": [
              "urn:li:geo:1"
         ],
         "impressions":29
      },
      { 
         "pivotValues": [
                "urn:li:geo:2"
         ],
         "impressions":28
      },
      { 
         "pivotValues": [
           "urn:li:geo:3"
         ],
         "impressions":28
      }
   ],
   "paging":{ 
      "count":10,
      "start":0,
      "links":[ 
         { 
            "rel":"next",
            "href":"/adAnalytics?q=analytics&timeGranularity=ALL&dateRange=(start:(day:28,month:7,year:2019))&start=10&count=10&pivot=_MEMBER_COUNTRY_V2&accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&fields=impressions,pivotValues",
            "type":"application/json"
         }
      ]
   }
}

---

Member County

http

GET https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=MEMBER_COUNTY&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=MEMBER_COUNTY&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

---

Sample Response

{ 
   "elements":[ 
      { 
         "pivotValues": [
           "urn:li:geo:1"
         ],
         "impressions":29
      },
      { 
         "pivotValues": [
           "urn:li:geo:2"
         ],
         "impressions":28
      },
      { 
         "pivotValues": [
           "urn:li:geo:3"
         ],
         "impressions":28
      }
   ],
   "paging":{ 
      "count":10,
      "start":0,
      "links":[ 
         { 
            "rel":"next",
            "href":"/adAnalyticsV2?q=analytics&timeGranularity=ALL&dateRange=(start:(day:28,month:7,year:2019))&start=10&count=10&pivot=_MEMBER_COUNTRY_V2&accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&fields=impressions,pivotValues",
            "type":"application/json"
         }
      ]
   }
}

URN Resolution

The URNs returned in the pivotValues field can be resolved to a human-readable name using the APIs in API URN Resolution

Sample Ad Analytics Request

The following sample gets analytics for each member country/region.

http

GET https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=(MEMBER_COUNTRY_V2)&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues

curl

curl -X GET 'https://api.linkedin.com/rest/adAnalytics?accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&dateRange=(start:(day:28,month:7,year:2019))&pivot=(MEMBER_COUNTRY_V2)&q=analytics&timeGranularity=ALL&fields=impressions,pivotValues' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Linkedin-Version: {version number in the format YYYYMM}' \
-H 'X-Restli-Protocol-Version: 2.0.0'

Sample Ad Analytics Response

{ 
   "elements":[ 
      { 
         "pivotValues": [
           "urn:li:geo:1"
         ],
         "impressions":29
      },
      { 
         "pivotValues": [
           "urn:li:geo:2"
         ],
         "impressions":28
      },
      { 
         "pivotValues": [
           "urn:li:geo:3"
         ],
         "impressions":28
      }
   ],
   "paging":{ 
      "count":10,
      "start":0,
      "links":[ 
         { 
            "rel":"next",
            "href":"/adAnalytics?q=analytics&timeGranularity.value=ALL&dateRange=(start:(day:28,month:7,year:2019))&start=10&count=10&pivot.value=_MEMBER_COUNTRY_V2&accounts=List(urn%3Ali%3AsponsoredAccount%3A511183580)&fields=impressions,pivotValues",
            "type":"application/json"
         }
      ]
   }
}

To resolve the above geo URN, we can use the Geo API to retrieve the country/region name.

Sample Geo Request

GET https://api.linkedin.com/v2/geo/1?locale=(language:en,country:US)

Sample Geo Response

{
  "defaultLocalizedName": {
    "locale": {
      "country": "US",
      "language": "en"
    },
    "value": "United States"
  },
  "id": 1
}