Partager via

Ad Supply Forecasts

  • Article

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.

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:

    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:
  • SPONSORED_UPDATES
  • SPONSORED_INMAILS
  • DYNAMIC
    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:
  • 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. 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:
  • 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

    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.