Ad Supply Forecasts
Warning
Deprecation Notice
The Marketing Version 202311 (Marketing November 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.
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. |
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. |
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: |
|
metricType | The forecast metric type. Metric types returned depend upon passed in values. Valid values include: |
|
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:
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}))))))&enableAudienceNetwork={true/false}&connectedTelevisionOnly={true/false}
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}))))))
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: For connected television campaigns, campaignType can only be SPONSORED_UPDATES. |
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: |
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. For connected television campaigns, enableAudienceNetwork must be set to true. | 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 |
connectedTelevisionOnly | Generate forecasting for connected television campaigns. Note: Applicable only from versions 202408 and above. | Boolean | Optional, default=false |
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
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)}))))
Encoded Sample Request
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))))
GET https://api.linkedin.com/v2/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}))))))
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: |
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: |
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
GET https://api.linkedin.com/v2/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)}))))
Encoded Sample Request
GET https://api.linkedin.com/v2/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))))
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} |
CTV_CAMPAIGN_WITHOUT_LAN_ENABLED_FOR_FORECAST | 422 | CTV campaigns require LAN to be enabled for forecasting. Note: Applicable only from versions 202408 and above. |
CTV_CAMPAIGN_INVALID_CAMPAIGN_TYPE_FOR_FORECAST | 422 | Currently only SPONSORED_UPDATES campaign type is supported for Forecasting with CTV campaign. Note: Applicable only from versions 202408 and above. |