Ad Supply Forecasts

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 Ad Supply Forecasts API enables you to forecast impressions, spending, and other metrics based on:

• Targeting criteria
• Campaign settings such as campaign type and objective type
• Bid and spending settings
• Time period

To calculate the forecast, we analyze these data points for your campaign, take into account campaign performance from similar campaigns/advertisers, and simulate the ad auction and serving processes. While we aim for utmost accuracy in our forecasts, it’s important to remember that forecasted results are an estimate and do not guarantee the actual performance of your campaign.

Permissions

Permission	Description
rw_ads	Manage and read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles. ACCOUNT_BILLING_ADMIN ACCOUNT_MANAGER CAMPAIGN_MANAGER CREATIVE_MANAGER
r_ads	Read an authenticated member's ad accounts. Restricted to ad accounts in which the authenticated member has one of the following ad account roles. ACCOUNT_BILLING_ADMIN ACCOUNT_MANAGER CAMPAIGN_MANAGER CREATIVE_MANAGER VIEWER

See Account Access Controls for more information on ad account roles.

Schema

The following schema table documents the fields responses will contain. Query parameters are documented separately for the criteriaV2 finder.

Field Name	Sub-Field Name	Description
granularity		The granularity of the forecast. Valid values: DAILY - Denotes per day for the forecast supply value. SEVEN_DAY - Denotes per a sum of the 7 days starting at the timestamp for the forecast supply value. THIRTY_DAY - Denotes that the forecast supply value is per a sum of the 30 days starting at the timestamp. CUSTOM - Denotes per a sum of a custom number of days sent in the dateRange of the forecasting client request for the forecast supply value starting at the timestamp.
metricType		The forecast metric type. Metric types returned depend upon passed in values. Valid values include: IMPRESSION - The number of ad impressions in a selected time period. The window starts at the specified timestamp with the length defined as the granularity. For Conversation Ad, this is the number of headline impressions in a selected time period CLICK - The number of ad clicks in a time window. The window starts at the specified timestamp with the length defined as the granularity. For Conversation Ad, this is the number of headline clicks in a time window. VIDEO_VIEW - The number of video views in a time window. The window starts at the specified timestamp with the length defined as the granularity. SPENDING - The amount spent in campaign currency. LEAD - The lead generated from the campaign. MAX_POTENTIAL_BUDGET - The max budget for the campaign. SPONSORED_INMAIL_SEND - The sponsored inmail send. CONVERSION - The conversion from campaign. CLICK_PER_MILLION_IMPRESSIONS - Forecasted number of clicks per one million campaign impressions, e.g. if the value is 1, the actual Click Through Rate should be 1/1000000. VIDEO_VIEW_PER_MILLION_IMPRESSIONS - The number of video views per one million campaign impressions, e.g. if the value is 1, the actual View Through Rate should be 1/1000000. LEAD_PER_MILLION_IMPRESSIONS - The number of leads per one million campaign impressions, e.g. if the value is 1, the actual Lead Through Rate should be 1/1000000. REACH - The projected number of unique member accounts that are shown your campaign ad at least once in a time window. Starts with the specified timestamp and ends according to the listed granularity. REACH_PER_MILLION_IMPRESSIONS - The projected reach per one million campaign impressions, in which reach is the estimated number of unique member accounts that are shown your campaign ad. e.g., if the value is 10,000, then the estimate indicates that your campaign ads will be shown to 10,000 unique member accounts for every million impressions. COST_PER_MILLION_IMPRESSIONS - The projected number of cost per one million impressions for the campaign. e.g., if the value is 1, the actual Cost Per Impression is 1/1000000. COST_PER_MILLION_CLICKS - The projected number of cost per one million clicks for the campaign. e.g., if the value is 1, the actual Cost Per Click is 1/1000000. COST_PER_MILLION_VIEWS - The projected number of cost per one million video views for the campaign. e.g., if the value is 1, the actual Cost Per Video View is 1/1000000. COST_PER_MILLION_LEADS - The projected number of cost per one million lead gen form submissions for the campaign. e.g., if the value is 1, the actual Cost Per Lead is 1/1000000. COST_PER_MILLION_REACHES - The projected number of cost per one million member accounts reached for the campaign. e.g., if the value is 1, the actual Cost Per Reach is 1/1000000. COST_PER_MILLION_MESSAGE_SENDS - The projected number of cost per one million messages sent for the campaign. e.g., if the value is 1, the actual Cost Per Message Send is 1/1000000.
timeSeries		Time series value for the forecast.
	timeStamp	The value timestamp. The time when the current forecast value is seen.
	value	Forecasting supply value at a specific time.
	adForecastRange	High and low range of the forecasting supply value at a specific time

Find Supply by CriteriaV2

The criteriaV2 finder uses the targetingCriteria format to return forecasts on particular audiences, bid configurations, and budgets. For more information on Targeting Criteria, see here.

Note

The forecast reflects the user's daily and total budgets. When the total budget is specified, part of the forecasted time series may show as a 0 after the user's budget is forecasted to run out, depending on the user's total and daily budget. The daily spending forecast is capped at 1.2x the daily budget. The result metrics (clicks, impressions, etc.) reflect the user's forecasted spending.

All API requests are represented in protocol 2.0.0 and require the header X-Restli-Protocol-Version: 2.0.0.

Restli 2.0 requires URNs in query params to be URL encoded. For example, urn:li:skill:17 would become urn%3Ali%3Askill%3A17.

Note that some API tools may not support these types of calls. Testing with curl is recommended if you encounter a 400 error with message Invalid query parameters passed to request.

Calls to this endpoint are structured as follows:

http

GET https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account={sponsored account urn}&campaignType={type}&timeRange.start={timestamp}&timeRange.end={timestamp} &targetingCriteria=(include:(and:List((or:({encoded facet_URN_1}:List({encoded facet_URN_1_value_1},{encoded facet_URN_1_value_2}))),(or:({encoded facet_URN_2}:List({encoded facet_URN_2_value_1},{encoded facet_URN_2_value_2}))))))

curl

curl -X GET 'https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account={sponsored account urn}&campaignType={type}&timeRange.start={timestamp}&timeRange.end={timestamp} &targetingCriteria=(include:(and:List((or:({encoded facet_URN_1}:List({encoded facet_URN_1_value_1},{encoded facet_URN_1_value_2}))),(or:({encoded facet_URN_2}:List({encoded facet_URN_2_value_1},{encoded facet_URN_2_value_2}))))))' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}'\
-H 'LinkedIn-Version: {version number in the format YYYYMM}' 

Parameters

Field Name	Description	Format	Required
q	This field should always be criteriaV2	String	Yes
account	The sponsored account for which the supply forecast is requested.	Sponsored Account URN	Required
campaignType	The campaign type. Valid values are: SPONSORED_UPDATES SPONSORED_INMAILS DYNAMIC	String	Required
campaign	The sponsored campaign, if available can be used to provide better forecasts	Sponsored Campaign URN	Optional
timeRange.start	Represents the inclusive start time range of the forecast. Must be after current UTC time. If unset, it will indicate an open range up to the end time.	String. Timestamp in milliseconds.	Required
timeRange.end	Represents the exclusive end time range of the forecast. Must be after start time. If unset, it will indicate an open range up of start time to everything after.	String. Timestamp in milliseconds.	Required
targetingCriteria	Specifies targeting criteria that the member should match. This is a more advanced boolean expression than the previous targeting field. It provides a generic AND / OR construct to include and exclude different targeting facets when defining the campaign audience.	targetingCriteria object	Required
creativeType	Creative type, if available can be used to provide better forecasts	creativeType	Optional
objectiveType	Objective type, if available can be used to provide better forecasts	objectiveType	Optional
competingBid.bidPrice.amount	Bid amount of the current campaign to forecast. Required for manual bid type forecasts. Required if other competingBid parameters are present.	String	Optional*
competingBid.bidPrice.currencyCode	Bid currency of the current campaign. Represented by the three character ISO currency codes (ie. USD). Required if other competingBid parameters are present.	String	Optional*
competingBid.bidType	Valid enum values are: CPM - Cost per thousand advertising impressions. CPC - Cost per individual click on the associated link. CPV - Cost per view for video ads Required for manual bid type forecasts. Required if other competingBid parameters are present.	String	Optional*
dailyBudget	Maximum amount to spend per day. The currency must match that of the parent account. The amount of money as a real number string. Required if totalBudget is not specified.	BigDecimal	Required if totalBudget not present in call
totalBudget	Maximum amount to spend over the life of the Campaign. The currency must match that of the Account. The amount of money as a real number string. Required if dailyBudget is not specified.	BigDecimal	Required if dailyBudget not present in call
optimizationTarget	The optimizationTargetType is used to optimize spending for a campaign. A forecast will be provided for auto-bidding when certain optimizationTargetTypes are provided. When optimizationTargetTypes is absent, you must provide the competingBid parameter for a manual bidding forecast.	Optimization Target Type	Optional, default="NONE"
enableAudienceNetwork	Include LinkedIn Audience Network inventory into campaign performance forecast.	Boolean	default=false
enableAudienceExpansion	Include Audience Expansion inventory into campaign performance forecast.	Boolean	default=false
targetCost	Target cost for Target CPX (where CPX stands for cost per X where X is a result such as an impression, click, etc.) campaigns. Target CPX is an optimization target type designed to maximize results while maintaining a daily cost per X (impression, click, etc.) as specified by the advertiser.	BigDecimal	Required only for optimization target type of target cost
costCap	Cost cap for Cost Cap bidding. This value is the maximum cost the advertiser is willing to pay per result (for example, click, mille impressions, video view).	BigDecimal	Required only for optimization target type of cost cap

Sample Request

The following shows a sample request forecasting the impressions of a Sponsored Update which targets members located in both Canada and the United States. The example request also excludes members working in organizations with more than 10,000 employees.

Any URNs included in the parameters must be URL encoded. An unencoded sample request has also been provided for readability.

Unencoded Sample Request

http

GET https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account=urn:li:sponsoredAccount:518121035&timeRange=(start:1526348264000,end:1529026664000)&campaignType=SPONSORED_UPDATES&dailyBudget=(amount:300,currencyCode:USD)&competingBid=(bidType:CPM,bidPrice:(currencyCode:USD,amount:10))&targetingCriteria=(include:(and:List((or:({encoded urn:li:adTargetingFacet:locations}:List({encoded urn:li:geo:102221843}))))),exclude:(or:({encoded urn:li:adTargetingFacet:staffCountRanges}:List({encoded urn:li:staffCountRange:(10001,2147483647)}))))

curl

curl -X GET 'https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account=urn:li:sponsoredAccount:518121035&timeRange=(start:1526348264000,end:1529026664000)&campaignType=SPONSORED_UPDATES&dailyBudget=(amount:300,currencyCode:USD)&competingBid=(bidType:CPM,bidPrice:(currencyCode:USD,amount:10))&targetingCriteria=(include:(and:List((or:({encoded urn:li:adTargetingFacet:locations}:List({encoded urn:li:geo:102221843}))))),exclude:(or:({encoded urn:li:adTargetingFacet:staffCountRanges}:List({encoded urn:li:staffCountRange:(10001,2147483647)}))))' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' 

Encoded Sample Request

http

GET https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account=urn%3Ali%3AsponsoredAccount%3A507001111&timeRange=(start:1566284400000,end:1568962800000)&campaignType=SPONSORED_UPDATES&totalBudget=(amount:100.00,currencyCode:USD)&competingBid=(bidType:CPM,bidPrice:(currencyCode:USD,amount:10))&targetingCriteria=(include:(and:List((or:(urn%3Ali%3AadTargetingFacet%3Alocations:List(urn%3Ali%3Ageo%3A101165590))))),exclude:(or:(urn%3Ali%3AadTargetingFacet%3AstaffCountRanges:List(urn%3Ali%3AstaffCountRange%3A%2810001%2C2147483647%29))))

curl

curl -X GET 'https://api.linkedin.com/rest/adSupplyForecasts?q=criteriaV2&account=urn%3Ali%3AsponsoredAccount%3A507001111&timeRange=(start:1566284400000,end:1568962800000)&campaignType=SPONSORED_UPDATES&totalBudget=(amount:100.00,currencyCode:USD)&competingBid=(bidType:CPM,bidPrice:(currencyCode:USD,amount:10))&targetingCriteria=(include:(and:List((or:(urn%3Ali%3AadTargetingFacet%3Alocations:List(urn%3Ali%3Ageo%3A101165590))))),exclude:(or:(urn%3Ali%3AadTargetingFacet%3AstaffCountRanges:List(urn%3Ali%3AstaffCountRange%3A%2810001%2C2147483647%29))))' \
-H 'X-Restli-Protocol-Version: 2.0.0' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'LinkedIn-Version: {version number in the format YYYYMM}' 

Sample Response

The API returns a list of AdSupplyForecast results based on the targetingCriteria parameters inputted from the previous example. Note that the metric forecasts that are returned are dependent on the request parameters, such as campaignType and objectiveType.

{  
   "elements":[  
      {  
         "metricType":"IMPRESSION",
         "timeSeries":[  
            {  
               "adForecastRange":{  
                  "lowEnd":38,
                  "highEnd":210
               },
               "value":180,
               "timestamp":1566259200000
            },
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"IMPRESSION",
         "timeSeries":[  
            {  
               "adForecastRange":{  
                  "lowEnd":270,
                  "highEnd":1500
               },
               "value":1200,
               "timestamp":1566259200000
            }
         ],
         "granularity":"SEVEN_DAY"
      },
      {  
         "metricType":"IMPRESSION",
         "timeSeries":[  
            {  
               "adForecastRange":{  
                  "lowEnd":1200,
                  "highEnd":6300
               },
               "value":5300,
               "timestamp":1566259200000
            }
         ],
         "granularity":"THIRTY_DAY"
      },
      {  
         "metricType":"IMPRESSION",
         "timeSeries":[  
            {  
               "adForecastRange":{  
                  "lowEnd":1200,
                  "highEnd":6700
               },
               "value":5600,
               "timestamp":1566259200000
            }
         ],
         "granularity":"CUSTOM"
      },
      {  
         "metricType":"CLICK",
         "timeSeries":[  
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"CLICK",
         "timeSeries":[  
            ...
         ],
         "granularity":"SEVEN_DAY"
      },
      {  
         "metricType":"CLICK",
         "timeSeries":[  
            ...
         ],
         "granularity":"THIRTY_DAY"
      },
      {  
         "metricType":"CLICK",
         "timeSeries":[  
            ...
         ],
         "granularity":"CUSTOM"
      },
      {  
         "metricType":"CLICK_PER_MILLION_IMPRESSIONS",
         "timeSeries":[  
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"SPENDING",
         "timeSeries":[  
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"SPENDING",
         "timeSeries":[  
            ...
         ],
         "granularity":"SEVEN_DAY"
      },
      {  
         "metricType":"SPENDING",
         "timeSeries":[  
            ...
         ],
         "granularity":"THIRTY_DAY"
      },
      {  
         "metricType":"SPENDING",
         "timeSeries":[  
            ...
         ],
         "granularity":"CUSTOM"
      },
      {  
         "metricType":"MAX_POTENTIAL_BUDGET",
         "timeSeries":[  
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"MAX_POTENTIAL_BUDGET",
         "timeSeries":[  
            ...
         ],
         "granularity":"SEVEN_DAY"
      },
      {  
         "metricType":"MAX_POTENTIAL_BUDGET",
         "timeSeries":[  
            ...
         ],
         "granularity":"THIRTY_DAY"
      },
      {  
         "metricType":"MAX_POTENTIAL_BUDGET",
         "timeSeries":[  
            ...
         ],
         "granularity":"CUSTOM"
      },
      {  
         "metricType":"COST_PER_MILLION_IMPRESSIONS",
         "timeSeries":[  
            ...
         ],
         "granularity":"DAILY"
      },
      {  
         "metricType":"COST_PER_MILLION_IMPRESSIONS",
         "timeSeries":[  
            ...
         ],
         "granularity":"SEVEN_DAY"
      },
      {  
         "metricType":"COST_PER_MILLION_IMPRESSIONS",
         "timeSeries":[  
            ...
         ],
         "granularity":"THIRTY_DAY"
      },
      {  
         "metricType":"COST_PER_MILLION_IMPRESSIONS",
         "timeSeries":[  
            ...
         ],
         "granularity":"CUSTOM"
      }
   ],
   "paging":{  
      "count":10,
      "start":0,
      "links":[  

      ]
   }
}

Error Codes

Below is a list of some possible error codes along with the Http status code and message templates that could be present in the response.

Code	HTTP Status Code	Error Message Template
MISSING_FIELD_FOR_FORECAST	422	The {field} is required but missing
DATE_BEFORE_TODAY_FOR_FORECAST	422	The {field} can't be before today. Update the {field} to be on or after {minValue}
START_DATE_AFTER_END_DATE_FOR_FORECAST	422	The campaign start date can't be after the campaign end date
END_DATE_MAX_HORIZON_FOR_FORECAST	422	Forecasted results aren't available for campaigns that end more than {maxValue} days from today
UNSUPPORTED_AUTO_BIDDING_CONVERSIONS_CAMPAIGN_SETUP_FOR_FORECAST	422	Forecasted results aren't available for maximum delivery bidding with a website conversions optimization goal
MISSING_LOCATION_ATTRIBUTE_FOR_FORECAST	422	The target audience is missing a location. Add at least one location
EMPTY_OR_INVALID_FOR_FORECAST	422	{field} is either empty or invalid
CONDITIONAL_VALUE_TOO_HIGH_FOR_FORECAST	422	The {field1} can't be higher than the {field2}
FIELD_VALUE_ABOVE_LIMITS_FOR_FORECAST	422	The {field} is over the maximum of {maxValue}
FIELD_VALUE_BELOW_LIMITS_FOR_FORECAST	422	The {field} must be at least {minValue}
INVALID_CURRENCY_CODE_FOR_FORECAST	422	Currency {value} is not supported for {field}
AUDIENCE_LIST_STILL_PROCESSING_FOR_FORECAST	422	Forecasting will update a few days after your selected lists have fully processed
AUDIENCE_COUNT_LESS_THAN_THRESHOLD_FOR_FORECAST	422	The target audience size is too small to show a forecast
INVALID_FIELD_FOR_OPTIMIZATION_TARGET	422	The field {field1} should not be passed in when optimization target type is {field2}
UNSUPPORTED_ENTITY	422	Forecasting does not support {field} {value}