Getting Started - Reporting
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
LinkedIn's Reporting APIs enable you to leverage LinkedIn marketing data to automate internal reporting and gain valuable insights. Partners can integrate LinkedIn data into their solutions to retrieve performance data, targeting information, audience insights, and much more. This guide provides a brief look at how these APIs can be used to provide valuable insights into audiences, impressions, targeting, and budgeting data.
- Audience Counts
- Ad Budget Pricing
- Ad Supply Forecasts
- Suggested Targeting Options
- Updating a Share with UTM Tracking Parameters
- Reporting
For a better picture of what the platform fully provides in functionality, read the Overview page or Campaign Management Getting Started.
Permissions
| Permission | Description |
|---|---|
| r_ads | Read an authenticated member's ad accounts. |
| r_ads_reporting | Retrieve reporting for advertising accounts. |
Audience Counts
The audienceCounts API allows you to forecast reach based on targeting criteria.
Audience Counts
The audienceCountsV2 API allows you to forecast reach based on targeting criteria.
Sample Request
The following request returns estimated audience counts for Canada and USA while excluding members who are in entry-level positions.
Sample Response
{
"elements": [
{
"active": 0,
"total": 150000000
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
See the targetingFacets reference page to learn more about targetingFacets and Audience Counts for more information on the Audience Counts API.
Ad Budget Pricing
With the adBudgetPricing API, you can get key insights on pricing metrics such as minimum, maximum, and suggested bids based on targeting criteria. The sample request returns pricing for an account based on target market criteria.
Sample Request
In the following example, the target market consists of LinkedIn members between the ages of 18 and 24.
Sample Response
{
"elements": [
{
"maxBid": {
"amount": "100.0",
"currencyCode": "USD"
},
"minBid": {
"amount": "0.3",
"currencyCode": "USD"
},
"suggestedBid": {
"amount": "2.06",
"currencyCode": "USD"
},
"suggestedBidRangeHighEnd": {
"amount": "2.11",
"currencyCode": "USD"
},
"suggestedBidRangeLowEnd": {
"amount": "2.01",
"currencyCode": "USD"
}
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
See the targetingFacets reference page to learn more about targetingFacets and Ad Budget Pricing for more information on the Ad Budget Pricing API.
Ad Supply Forecasts
The adSupplyForecasts API provides impression and budget data based on target set, bid, and time period.
Sample Request
The following sample request forecasts the impressions of a sponsored update for Canada and USA while excluding members in entry-level positions.
GET https://api.linkedin.com/rest/adSupplyForecasts?q=criteria&timeRange.start=1464804127000&timeRange.end=1465581727000&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3&campaignType=SPONSORED_UPDATES&competingBid.bidType=CPM&competingBid.bidPrice.currencyCode=USD&competingBid.bidPrice.amount=10
GET https://api.linkedin.com/v2/adSupplyForecasts?q=criteria&timeRange.start=1464804127000&timeRange.end=1465581727000&target.includedTargetingFacets.locations[0]=urn:li:geo:101174742&target.includedTargetingFacets.locations[1]=urn:li:geo:103644278&target.excludingTargetingFacets.seniorities[0]=urn:li:seniority:3&campaignType=SPONSORED_UPDATES&competingBid.bidType=CPM&competingBid.bidPrice.currencyCode=USD&competingBid.bidPrice.amount=10
Sample Response
{
"elements": [
{
"timeSeries": [
{
"value": 22874,
"timestamp": 1485302400000
},
{
"value": 2244802,
"timestamp": 1485388800000
},
{
"value": 1869223,
"timestamp": 1485475200000
},
{
"value": 1098326,
"timestamp": 1485561600000
},
...
],
"metricType": "IMPRESSION",
"granularity": "DAILY"
}
],
"paging": {
"count": 10,
"start": 0,
"links": []
}
}
For more information on the Ad Supply Forecasts API, check out Ad Supply Forecasts.
Suggested Targeting Options
The LinkedIn Ads platform allows you to reach a wide range of audiences based on unique targeting criteria. The Ad Targeting Similar Entities finder suggests additional targeting attributes based on a provided target set.
Sample Request
The following example returns industries similar to Biotechnology, urn:li:industry:12.
Sample Response
{
"elements": [
{
"value": {
"string": "urn:li:industry:15",
"string~": {
"name": {
"localized": {
"en_US": "Pharmaceuticals"
}
}
}
}
},
{
"value": {
"string": "urn:li:industry:17",
"string~": {
"name": {
"localized": {
"en_US": "Medical Device"
}
}
}
}
},
{
"value": {
"string": "urn:li:industry:13",
"string~": {
"name": {
"localized": {
"en_US": "Medical Practice"
}
}
}
}
},
...
]
}
To learn more about Targeting by Similar Entities, see the Ad Targeting page.
Updating a Share with UTM Tracking Parameters
URLs in shares can be updated to include UTM parameters for advertisers to track the success of marketing efforts and prove ROI. This feature allows retroactive modification of URLs contained within shares.
To update UTM parameters, you must know the share URN and content of the share. For more information on how to leverage this feature, see UTM Tracking.
POST https://api.linkedin.com/rest/sharesUrl/{shareURN}
{
"patch": {
"content": {
"$set": {
"contentEntities": [
{
"description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
"entity": "urn:li:article:8302773461016502828",
"entityLocation": "https://www.yahoo.com?utm_campaign=blogpost&utm_medium=social&utm_source=facebook",
"thumbnails": [
{
"imageSpecificContent": {
"height": 200,
"size": 5992,
"width": 200
},
"resolvedUrl": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png"
}
],
"title": "Test Share with Content !!"
}
]
}
}
}
}
POST https://api.linkedin.com/v2/sharesUrl/{shareURN}
{
"patch": {
"content": {
"$set": {
"contentEntities": [
{
"description": "News, email and search are just the beginning. Discover more every day. Find your yodel.",
"entity": "urn:li:article:8302773461016502828",
"entityLocation": "https://www.yahoo.com?utm_campaign=blogpost&utm_medium=social&utm_source=facebook",
"thumbnails": [
{
"imageSpecificContent": {
"height": 200,
"size": 5992,
"width": 200
},
"resolvedUrl": "https://s.yimg.com/dh/ap/default/130909/y_200_a.png"
}
],
"title": "Test Share with Content !!"
}
]
}
}
}
}
Ad Analytics
The Ad Analytics API provides account, campaign, and creative level statistics on current spend as well as chargeable clicks and impressions. To learn more, see Reporting.
Sample Request
The following example returns analytics from January 1, 2016 for campaign ID 10002907 with a monthly time granularity and pivoting based on creatives.
Sample Response
{
"elements": [
{
"chargeableClicks": 59,
"dateRange": {
"end": {
"day": 18,
"month": 9,
"year": 2016
},
"start": {
"day": 1,
"month": 1,
"year": 2016
}
},
"impressions": 8456,
"nonchargeableClicks": 1,
"pivot": "urn:li:sponsoredCampaign:10002907",
"spend": {
"amount": "142.00",
"currencyCode": "USD"
}
}
],
"paging": {
"count": 10,
"start": 0
}
}
Share & Social Action Insights
Share and Social Action APIs provide insights into share, like, and comment statistics. This data can be used to optimize organic and sponsored content performance.
Find Share by URN
Sample Response
{
"activity": "urn:li:activity:6230438468758052864",
"content": {
"contentEntities": [
{
"entity": "urn:li:article:6994272117874578221",
"entityLocation": "http://www.lemondeinformatique.fr/actualites/lire-business-france-emmene-des-start-ups-au-web-summit-de-lisbonne-66405.html?utm_source=Sociallymap&utm_medium=Sociallymap&utm_campaign=Sociallymap"
}
],
"description": "8 start-ups fran\u00e7aises IT ont \u00e9t\u00e9 s\u00e9lectionn\u00e9es parmi 60 candidates par la d\u00e9l\u00e9gation Business France pour participer au Web Summit 2016 qui aura...",
"title": "Business France emm\u00e8ne des start-ups au Web Summit de Lisbonne - Le Monde Informatique"
},
"created": {
"actor": "urn:li:person:uex10Z3oFO",
"time": 1485452286000
},
"distribution": {
"linkedInDistributionTarget": {}
},
"edited": false,
"id": "6230438468804177920",
"lastModified": {
"actor": "urn:li:person:uex10Z3oFO",
"time": 1485452286000
},
"owner": "urn:li:organization:2414183",
"text": {
"text": "Business France emm\u00e8ne des start-ups au Web Summit de Lisbonne #airmisconseil"
}
}
Social Actions
Shares may have social actions such as likes and comments attached to them. With the socialActions API, you can view social actions on various types of network updates. To learn more about retrieving social actions, see Network Update Social Action.
Find Comments for a Share
Sample Response
{
"elements": [
{
"created": {
"time": 1485303622383
},
"id": "6229814924525211648",
"lastModified": {
"time": 1485303622383
},
"message": {
"attributes": [],
"text": "This is a comment"
},
"object": "urn:li:activity:6229788468420055040"
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}
Find Likes for a Share
Sample Response
{
"elements": [
{
"created": {
"time": 1485303834338
},
"lastModified": {
"time": 1485303834515
},
"object": "urn:li:activity:6229788468420055040"
}
],
"paging": {
"count": 10,
"links": [],
"start": 0
}
}