Use Media Planner with the Pinterest API
Pinterest's Media Planner helps you streamline media planning by testing various campaign configurations before creating your actual campaign.
Media Planner is available for campaigns with , and objectives.
LEADSSALESCONSIDERATIONLegacy and objectives remain supported until February 1, 2027.
WEB_CONVERSIONCATALOG_SALESWith Media Planner, you can create future campaign media plans using the same campaign configuration you would use in Ads Manager. You can see estimates and forecasts of campaigns' predicted performance and discover areas of opportunity.
See this guide for using the API to generate and review campaign projections to determine the right budget and media needed to accomplish your goals.
Prerequisites
What you need | Why you need it | How to get it |
|---|---|---|
OAuth access token with ads:read | The delivery estimates call is an Ads API read. | Create or use an OAuth app and generate a token with the ads:read |
Ad account ID your token can access | The path is /v5/ad_accounts/{ad_account_id}/campaigns/delivery_estimates | Use an ad account owned or authorized for that OAuth token (Ads Manager or GET ad accounts). |
Campaign dates and budget | Required to simulate the plan ( start_datebudget_duration_typelifetime_spend_capdaily_spend_cap | Use the same values you would use to create the campaign. Spend caps are microcurrency ($10 USD = 10000000 |
Conversion tag + conversion metadata (for LEADSSALESWEB_CONVERSION | Lower-funnel estimates need optimization_goal_metadata.conversion_tag_v3_goal_metadataOptimizationGoalMetadata is not set for adgroup 0 | Use an ACTIVE conversion tag on the ad account. Send conversion_eventconversion_tag_idattribution_windowsLEADSIGNUPLEADSCHECKOUTADD_TO_CARTSALES |
Catalog / shopping setup (only if estimating catalog ads) | Catalog shopping uses intended_promotion_type: CATALOGcreative_types: ["SHOPPING"]CONSIDERATIONSALESCATALOG_SALES | Use REST snake_case intended_promotion_typeintendedPromotionTypeproduct_group_ids |
Generate estimates
Request:
https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/campaigns/delivery_estimatesRequest parameters
These parameters mirror the structure of campaign and ad group creation endpoints, and you can use them to simulate a campaign with child ad groups.
As you start to generate delivery estimates, you can adjust your targeting, budget, or bid and then generate new estimates to see how they change.
The request body is always a JSON array containing exactly one campaign object ().
maxItems: 1A bare object is invalid.
Access to this endpoint is granted on your OAuth app (the API client you registered), not on individual ad accounts.
You can still use the legacy objective with creatives. Optional apply to catalog shopping campaigns only.
CATALOG_SALESSHOPPINGproduct_group_idsParameter | Description |
|---|---|
objective_typeString Required | Campaign objective. Set to one of the following currently supported objectives:
For catalog shopping estimates under objective simplification, set objective_typeCONSIDERATIONSALESintended_promotion_typeCATALOGad_groups[].creative_types["SHOPPING"]For LEADSSALESWEB_CONVERSIONoptimization_goal_metadata.conversion_tag_v3_goal_metadataconversion_eventconversion_tag_idattribution_windowsUse LEADSIGNUPLEADSCHECKOUTADD_TO_CARTSALESOptimizationGoalMetadata is not set for adgroup 0Prefer LEADSSALESWEB_CONVERSIONCATALOG_SALES |
budget_duration_typeString Required | Duration type of the campaign budget.
|
intended_promotion_typeString Required when objective_type is SALESCONSIDERATION | Creative source for ads in this campaign.
- CATALOGCONSIDERATIONSALEScreative_types: ["SHOPPING"]- LEGACYCATALOG_SALESWEB_CONVERSIONRequired when objective_typeSALESCONSIDERATION |
daily_spend_capInteger Required when budget_duration_typeFIXED_DAILYFLEXIBLE_DAILY | Set the amount in microcurrency. Example: For $10 USD, set the value as 10000000. Do not use this parameter if you are using lifetime_spend_cap |
lifetime_spend_capInteger Required when budget_duration_typeLIFETIME | Set the amount in microcurrency. Example: For $10 USD, set the value as 10000000. Do not use this parameter if you are using daily_spend_cap |
start_dateString Required | Set the campaign start date for the time period you want to include in the estimate. Format: YYYY-MM-DD |
end_dateString Required when budget_duration_typeLIFETIME | Set the campaign end date for the time period you want to include in the estimate. Format: YYYY-MM-DDRequired for lifetime budgets. Optional for daily budgets. |
ad_groupsArray of objects Required | Container for child ad groups of the campaign for which you want to generate an estimate. You can include a maximum of 10 ad groups with this current release. |
ad_groups.creative_typesArray of strings Optional | Set the creative types that you want to include in the estimate. Use SHOPPINGCATALOG_SALESCONSIDERATIONSALESintended_promotion_type: CATALOG |
ad_groups.product_group_idsArray of strings Optional | Targeted product group IDs for catalog shopping estimates. Use only with shopping/catalog campaigns ( CATALOG_SALESCONSIDERATIONSALESintended_promotion_type: CATALOG |
ad_groups.optimization_goal_metadataObject Required for LEADSSALESWEB_CONVERSION | Conversion (or frequency) metadata for the ad group. For LEADS, SALESWEB_CONVERSIONconversion_tag_v3_goal_metadata
Not required for AWARENESSCONSIDERATION |
ad_groups.keywordsArray of objects Optional | To generate estimates for campaigns that are keyword-targeted, set a list of search keywords that you want your ads to target. See following two child parameters. |
ad_groups.keywords.match_typeObject Required for keywords | Indicate how strictly the keywords should be matched to user searches or content. BROADExample: Keyword shoes may match running shoes, buy sneakers, comfortable footwear, and others. PHRASEExample: Keyword red dress may match buy red dress, red dress for party, but not dress in red. EXACTExample: Keyword wedding invitations may match wedding invitations, wedding invitation (singular), but not cheap wedding invitations online. EXACT_NEGATIVEExample: For keyword free samples, ad will not show for free samples, but could show for samples for sale. PHRASE_NEGATIVEExample: For keyword discount shoes, ad will not show for buy discount shoes, discount shoes for men, and others. |
ad_groups.keywords.valueString Required for keywords | Set the keyword that you want your ads to target. Maximum 250 characters. To include multiple keywords in your estimate, use multiple keyword objects. |
ad_groups.targeting_specObject Required | Define the audience in the child ad group of the campaign for which you want to generate an estimate. Location or geo targeting is required. Include at least one location for each ad group. Missing targeting_spec |
Response fields
Field | Description |
|---|---|
curvesArray of objects | Each object in the array represents a reporting event and shows how the estimated outcome for that event changes as your bid changes. |
curves.pointsArray of objects | Array of data points, each corresponding to a specific bid value and the estimated minimum and maximum outcome (such as impressions or clicks) at that bid. |
curves.points.budgetInteger | Budget value associated with the estimate point, in microcurrency — the same unit as request spend caps. Example: 10000000min_ymax_yydouble_y |
curves.points.min_yInteger | Minimum estimated value for the reporting event at this bid/budget. |
curves.points.max_yInteger | Maximum estimated value for the reporting event at this bid/budget. |
curves.points.yInteger | Expected (average or median) value for the reporting event at this bid/budget. |
curves.points.double_yNumber | Floating-point version of yCONVERSIONCPA |
curves.estimation_typeString | Method or approach Pinterest used to generate the delivery estimate:
|
max_potential_spendInteger | Estimated maximum potential spend. |
derived_metricsObject | Container for all estimated metrics for an ad campaign. |
derived_metrics.cpcFloat | Estimated cost per click in the ad account currency (for example 0.56 USD). Not microcurrency. |
derived_metrics.cpc_upperFloat | High-end cost-per-click estimate in the ad account currency. |
derived_metrics.cpc_lowerFloat | Low-end cost-per-click estimate in the ad account currency. |
derived_metrics.weekly_clickFloat | Estimated weekly clicks. |
derived_metrics.weekly_click_upperFloat | High-end estimate of weekly clicks. |
derived_metrics.weekly_click_lowerFloat | Low-end estimate of weekly clicks. |
derived_metrics.cpmFloat | Estimated cost per thousand impressions in microdollars (µUSD). |
derived_metrics.cpm_upperFloat | High-end estimate of cost per thousand impressions in microdollars (µUSD). |
derived_metrics.cpm_lowerFloat | Low-end estimate of cost per thousand impressions. |
derived_metrics.weekly_frequencyFloat | Estimated number of times a unique user will see your ad in a week. |
derived_metrics.weekly_frequency_upperFloat | High-end estimate of the number of times a unique user will see your ad in a week. |
derived_metrics.weekly_frequency_lowerFloat | Low-end estimate of the number of times a unique user will see your ad in a week. |
derived_metrics.weekly_reachFloat | Estimated number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_reach_upperFloat | Upper estimate of number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_reach_lowerFloat | Lower estimate of number of unique users who will see your ad at least once during a one-week period. |
derived_metrics.weekly_impressionFloat | Estimated number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.weekly_impression_upperFloat | Upper estimate of number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.weekly_impression_lowerFloat | Lower estimate of number of times your ad will be shown (served) to users during a one-week period—whether they are the same or different users. |
derived_metrics.lifetime_reachFloat | Estimated number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_reach_upperFloat | Upper estimate of number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_reach_lowerFloat | Lower estimate of number of unique users who will see your ad at least once over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_impressionFloat | Estimated number of times your ad will be shown (served) to users over the lifetime of the campaign—whether they are the same or different users. Returned for AWARENESSWEB_CONVERSIONLEADSSALES |
derived_metrics.lifetime_impression_upperFloat | Upper estimate of number of times your ad will be shown (served) to users over the lifetime of the campaign. Returned for AWARENESSWEB_CONVERSIONLEADSSALES |
derived_metrics.lifetime_impression_lowerFloat | Lower estimate of number of times your ad will be shown (served) to users over the lifetime of the campaign. Returned for AWARENESSWEB_CONVERSIONLEADS, SALES |
derived_metrics.lifetime_frequencyFloat | Estimated number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_frequency_upperFloat | Upper number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_frequency_lowerFloat | Lower estimate of number of times a unique user will see your ad over the lifetime of the campaign. Only applicable to AWARENESS |
derived_metrics.lifetime_clickderived_metrics.lifetime_click_upperderived_metrics.lifetime_click_lowerFloat | Estimated clicks over the campaign lifetime, with high and low bounds. Returned for CONSIDERATIONCONSIDERATION |
derived_metrics.cpaderived_metrics.cpa_lowerFloat | Estimated cost per action, with a low bound. Returned for WEB_CONVERSIONLEADSSALEScpa_upper |
derived_metrics.lifetime_conversionderived_metrics.lifetime_conversion_upperderived_metrics.lifetime_conversion_lowerFloat | Estimated conversions over the campaign lifetime, with high and low bounds. Returned for WEB_CONVERSIONLEADSSALES |
derived_metrics.weekly_conversionderived_metrics.weekly_conversion_upperderived_metrics.weekly_conversion_lowerFloat | Estimated conversions per week, with high and low bounds. Returned for WEB_CONVERSIONLEADSSALES |
Examples
Every request body is a one-element array. Numeric estimate values vary by ad account, targeting, and date range; treat the JSON as schema, not expected volume.
Example for objective type AWARENESS with lifetime budget
Request
Response for objective type AWARENESS with lifetime budget
Sample UI Output
This screenshot shows the objective type AWARENESS with a lifetime budget.
Example for Objective Type CONSIDERATION with Lifetime Budget
Request
Response for Objective Type CONSIDERATION with Lifetime Budget
Sample UI Output
This screenshot shows the objective type with a lifetime budget.
CONSIDERATION
Example for CONSIDERATION catalog shopping with lifetime budget
Use this pattern for catalog shopping estimates under objective simplification. The same + combination is valid with . Response shape matches other estimates ( / curves). REST requires snake_case .
SHOPPINGCATALOGobjective_typeSALESCONSIDERATIONCLICKCPCintended_promotion_typeRequest
Example for objective type LEADS with lifetime budget
LEADSWEB_CONVERSIONIMPRESSIONCPMCONVERSIONCPAderived_metricscpacpa_lowercpa_upperlifetime_conversionweekly_conversionRequest
Example for objective type SALES with lifetime budget
SALESWEB_CONVERSIONCATALOG_SALESintended_promotion_typeCATALOGFor Pin-based sales, use and conversion event or .
STANDARD_ADCHECKOUTADD_TO_CARTFor catalog sales, set to and to .
intended_promotion_typeCATALOGcreative_types["SHOPPING"]Response shape matches other conversion estimates ( /).
CONVERSION CPA curvesRequest
Was this page helpful?