Share via

Reporting

Warning

Deprecation Notice: The Marketing Version 202503 (Marketing March 2025) has been sunset. We recommend that you migrate to the latest versioned APIs to avoid disruptions. For information on all the supported versions, refer to the migrations documentation. If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.

Try in Postman

The LinkedIn Reporting APIs provide key insights on performance such as clicks, impressions, ad spend and professional demographics information such as metrics by professional demographic values at the account, campaign or creative levels.

Permissions

Permission Description
r_ads_reporting Retrieve reporting for advertising accounts.

Ad Analytics

The adAnalytics endpoint supports three finder methods:

Note

  • The adAnalytics endpoint currently does not support pagination.
  • Some metrics are not available with professional demographic pivots. These are noted in the metrics available table.
  • An empty response is returned if there's no activity to report or if you don't have read access to the requested advertising data.
  • Requests to adAnalytics can have a long list of query parameters 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.

The adAnalytics endpoint supports two finder methods:

  • Analytics: Use to group by one element (pivot).
  • Statistics: Use to group by up to three elements.

Note

  • The adAnalytics endpoint currently does not support pagination.
  • Some metrics are not available with professional demographic pivots. These are noted in the metrics available table.
  • An empty response is returned if there's no activity to report or if you don't have read access to the requested advertising data.
  • Requests to adAnalytics can have a long list of query parameters 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. Following are the types of requests and their retention periods:

  • Requests for performance data (for example, by account, campaign, or creative) are retained for ten (10) years.
  • Professional demographics data (for example, by member title, job function, or seniority) is retained for two (2) years.

Restrictions

The following restrictions apply based on your query parameters.

  • An empty response is returned if there's no activity to report or if you don't have read access to the requested advertising data.
  • Pagination is not supported.
  • Some metrics are not available with specific pivots (e.g. conversion or professional demographics pivots). These are noted in the metrics available table.
  • When timeGranularity=ALL, if either the start or end date of a request range is outside 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. 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.
  • Professional Demographic pivots only support the top 100 professional demographic values for each creative for each day. Example: If a creative is shown to members with 1,000 different titles, a query for the impressions for that creative with a MEMBER_JOB_TITLE pivot returns the 100 titles with the most impressions for that creative for that day.
  • Professional Demographic values are not returned for ads receiving engagement from too few members.
  • Professional Demographic pivots have a minimum threshold of 3 events. Professional Demographic values with less than 3 events are dropped from the query results.
  • Professional Demographic pivots don't support carousel metrics.

Delays

Performance metrics such as metrics about a creative, campaign, or account are near real-time. Metrics based on any member professional demographics such as company size and job function can be delayed by 12 to 24 hours.

The videoWatchTime and averageVideoWatchTime metrics are subject to a delay of up to 48 hours.

Accuracy

To protect LinkedIn member privacy, professional demographic metrics are approximate. To learn more about this approximation, refer to this article.

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

  • Similar time ranges. Example: Reporting on results over 7 days vs 8 days.
  • The sum of daily metrics to the full corresponding time period.
  • Reporting levels. 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. 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 can include companies that were not targeted in a campaign even if the advertiser explicitly targeted specific companies to see their campaign. This is possible for any of the following reasons:

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

Metrics Available

For more details on the schema information, refer to the Metrics Available table.

Professional Demographic Pivot Fields Restrictions

The following fields are present only for non-demographic pivots (i.e. not MEMBER_):

  • conversionValueInLocalCurrency
  • cardImpressions
  • cardClicks
  • viralCardImpressions
  • viralCardClicks
  • approximateMemberReach

Analytics Finder

Try in Postman

The Analytics Finder is used to specify a single pivot.

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

Query Parameters

For more details on the query parameters information, refer to the Query Parameters table.

Sample Request

The following sample request returns creative level analytics for a particular campaign beginning in 2024.

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

Sample Response

{
    "elements": [
        {
            "clicks": 177,
            "impressions": 54494,
            "dateRange": {
                "end": {
                    "day": 24,
                    "month": 5,
                    "year": 2025
                },
                "start": {
                    "day": 1,
                    "month": 1,
                    "year": 2024
                }
            },
            "pivotValues": [
                "urn:li:sponsoredCreative:1234567"
            ]
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Note

  • We currently don't 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

LinkedIn requires you to mention specific metrics in a request, using the fields query parameter. Otherwise, only impressions and clicks are returned by default. Request up to 20 metrics. The following metrics are supported:

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

Note

Each metric is separated by a comma after the fields= keyword.

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

Sample Request

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

Sample Response

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

Data Throttling

LinkedIn limits the amount of data that can be requested from this endpoint within a short time window. If an application exceeds the upper limit of data returned in a 5-minute window, requests are throttled. To reduce data load, use field parameters as described in the Requesting Specific Fields in the Analytics Finder.

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 request/response:

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

Statistics Finder

Try in Postman

The Statistics Finder can be used to specify up to three pivots.

LinkedIn requires you to specify metrics in your request using the fields query parameter. Otherwise, only impressions and clicks are returned by default. You can request up to 20 metrics. For an example of a request that calls specific metrics, refer to Requesting Specific Fields in the Analytics Finder.

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})

Query Parameters

For more details on the query parameters information, refer to the Query Parameters table.

Sample Request

The following sample request returns campaign level statistics for a particular ad account beginning in 2024.

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

Sample Response

{
    "elements": [
        {
            "clicks": 177,
            "impressions": 54494,
            "dateRange": {
                "end": {
                    "day": 23,
                    "month": 5,
                    "year": 2025
                },
                "start": {
                    "day": 1,
                    "month": 1,
                    "year": 2024
                }
            },
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ]
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Attributed Revenue Metrics Finder

Try in Postman

The Attributed Revenue Metrics Finder can be used when specifying up to three pivots to demonstrate LinkedIn marketing’s influence on revenue using your CRM data. For more information, refer to the Revenue Attribution Report.

Prerequisites

To share your CRM data to Campaign Manager:

Considerations

  • The RevenueAttributionMetrics are only available for accounts that have connected their CRM to LinkedIn.
  • After you’ve connected your CRM data to Campaign Manager, it can take up to 72 hours initially for data to be available in the response.
  • Only ACCOUNT, CAMPAIGN_GROUP, CAMPAIGN pivots are supported.
  • Metrics are only available within the last 1 year date range, so the dateRange must be between 30 and 366 days (inclusive).
  • opportunityAmountInUsd and openOpportunities are available only when dateRange.end is set to today's date in UTC. Otherwise, these two fields are not returned.
  • You can collate Revenue Attribution Metrics with other ad metrics (like impressions, clicks) by matching with same pivots and dateRange in other finders.

Requesting specific metrics in the Attributed Revenue Metrics Finder

Use fields=revenueAttributionMetrics to retrieve all metrics in the RevenueAttributionMetrics object. Alternatively, specify individual metrics by including them in the fields parameter, such as fields=dateRange,pivotValues,revenueAttributionMetrics:(openOpportunities,revenueWonInUsd). Refer to Field Projections for more details on using field projections.

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

Query Parameters

Parameter Description Format Required
q Designates the query finder. This must be set to attributedRevenueMetrics for the Attributed Revenue Metrics Finder. String Yes
pivots Pivot of results, by which each report data point is grouped. Accepts up to 3 values. The following enum values are supported:
  • CAMPAIGN - Group results by campaign.
  • CAMPAIGN_GROUP - Group results by campaign group.
  • ACCOUNT - Group results by account.
 Array of Strings Yes
dateRange.start Represents the inclusive start time range of the analytics. Start date should be within the last 1 year. Date object Yes
dateRange.end Represents the inclusive end time range of the analytics. The field 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
account Match result by sponsored ad account facet. Account URN Yes
campaigns Match result by campaign facets. Defaults to empty. Array of Sponsored Campaign URN No
campaignGroups Match result by campaign group facets. the default value is set to empty. Array of Campaign Group URN No

Sample Request

The following sample groups Revenue Attribution Metrics by Campaign for a particular ad account for the year 2025.

GET https://api.linkedin.com/rest/adAnalytics?q=attributedRevenueMetrics&fields=revenueAttributionMetrics,dateRange,pivotValues&dateRange=(start:(year:2025,month:03,day:1),end:(year:2025,month:05,day:31))&account=List(urn%3Ali%3AsponsoredAccount%3A12345)&pivots=List(ACCOUNT)

Sample Response

{
    "elements": [
        {
          "revenueAttributionMetrics": {
                "returnOnAdSpend": 10.0,
                "openOpportunities": 200,
                "opportunityWinRate": 0.75,
                "revenueWonInUsd": "1000.0",
                "closedWonOpportunities": 100,
                "opportunityAmountInUsd": "2000.0",
                "averageDaysToClose": 75.0,
                "averageDealSizeInUsd": "10.0"
          },
          "dateRange": {
                "end": {
                    "day": 31,
                    "month": 12,
                    "year": 2025
                },
                "start": {
                    "day": 1,
                    "month": 1,
                    "year": 2025
                }
            },
            "pivotValues": [
                "urn:li:sponsoredCampaign:1234567"
            ]
        }
    ],
    "paging": {
        "count": 10,
        "links": [],
        "start": 0
    }
}

Reporting Microsoft Bing Locations

The ad reporting mechanism now uses the Microsoft Bing location dataset. In addition to targeting, the adAnalytics endpoint adds new professional demographic pivots for Bing location information for the following professional 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're agreeing to be bound by these Microsoft terms.

Member Country

Sample Request

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

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

Sample Request

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

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

Sample Request

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

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.

Ad Analytics Sample Request

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

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

Ad Analytics 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"
         }
      ]
   }
}

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

Geo Sample Request

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

Geo Sample Response

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

API Error Details

HTTP Status Code Error Message Description
400 MISSING_FIELD A required query parameter is missing. Ensure required parameters such as q, pivot (Analytics Finder), or pivots (Statistics Finder) are included in the request.
400 INVALID_VALUE_FOR_FIELD An invalid value was provided for a query parameter. Verify that values for pivot, timeGranularity, and other enum parameters are valid.
400 START_DATE_AFTER_END_DATE The start date cannot be after the end date. Verify that dateRange.start is set to a date earlier than dateRange.end.
400 DATE_TOO_EARLY The date value is before the allowed minimum. The requested date is outside the supported retention period.
401 EMPTY_ACCESS_TOKEN Authentication failed. Ensure a valid, non-empty, non-expired OAuth2 access token is included in the Authorization header.
403 USER_NOT_AUTHORIZED The user does not have access to the requested advertising data. Ensure the r_ads_reporting permission is granted and the authenticated user has access to the specified account, campaign, or creative URN.
404 NOT_FOUND The requested resource was not found. Verify that the account, campaign, or creative URN provided in the request is correct.
414 REQUEST_URI_TOO_LONG The request URL exceeds the maximum allowed length. Use query tunneling when the list of query parameters is too long.
429 TOO_MANY_REQUESTS The data request limit has been exceeded. More than 45 million metric values were requested in a 5-minute window. Reduce data load by specifying only required fields using the fields parameter.
500 INTERNAL_ERROR An unexpected server-side error occurred. Retry the request.
503 UNDER_MAINTENANCE The service is temporarily unavailable. Retry the request after a brief delay.
  • Last updated on