--- title: "Get campaign delivery estimates" method: POST path: "/ad_accounts/{ad_account_id}/campaigns/delivery_estimates" tags: ["campaigns"] --- # Get campaign delivery estimates `POST /ad_accounts/{ad_account_id}/campaigns/delivery_estimates` Get delivery estimates for an ads campaign **This endpoint is currently in beta and is not available to all apps [Learn more](/docs/new/about-beta-access/).** ## Path parameters - `ad_account_id` string, required ## Request body - CampaignDeliveryEstimatesCampaign[] — Campaign delivery estimates request body. - `ad_groups` AdGroupDeliveryEstimates[], required - `auto_targeting_enabled` boolean - `creative_types` AdGroupAudienceSizingCreativeTypes[] — Pin creative types filter. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. - `keywords` AdGroupDeliveryEstimatesKeywordsItems[], nullable — Array of keyword objects. If the keywords field is missing, all keywords will be targeted. - `match_type` 'BROAD' | 'PHRASE' | 'EXACT' | 'EXACT_NEGATIVE' | 'PHRASE_NEGATIVE' | 'null', nullable, required — Keyword match type allowing null - `value` string, required — Keyword value (120 chars max). - `monthly_frequency_cap` integer — Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. - `optimization_goal_metadata` OptimizationGoalMetadata - `conversion_tag_v3_goal_metadata` ConversionTagV3GoalMetadata - `attribution_windows` AttributionWindows - `click_window_days` integer - `engagement_window_days` integer - `view_window_days` integer - `conversion_event` 'PAGE_VISIT' | 'SIGNUP' | 'CHECKOUT' | 'CUSTOM' | 'VIEW_CATEGORY' | 'SEARCH' | 'ADD_TO_CART' | 'WATCH_VIDEO' | 'LEAD' | 'APP_INSTALL' - `conversion_tag_id` string - `cpa_goal_value_in_micro_currency` string - `is_roas_optimized` boolean, nullable — Pinterest Performance+ ROAS bidding. When enabled, Pinterest will optimize for conversion value instead of conversion volume. Only supported when `conversion_event` is set to `"CHECKOUT"` and `bid_strategy_type` is set to `"AUTOMATIC_BID"`. This parameter is not enabled for all advertisers. [Learn more](https://developers.pinterest.com/docs/getting-started/using-beta-and-restricted-features/). - `reporting_event` string — Event name for custom or standard events mapped to an oCPM model - `frequency_goal_metadata` FrequencyGoalMetadata — Frequency target can only be between 2 and 20 - `frequency` integer - `timerange` 'THIRTY_DAY' | 'DAY' | 'SEVEN_DAY' | 'TWENTY_MINUTE' | 'TEN_MINUTE' | 'TWENTY_FOUR_HOUR' - `scrollup_goal_metadata` ScrollupGoalMetadata - `scrollup_goal_value_in_micro_currency` string, nullable - `optimization_type` 'CLICKTHROUGH' | 'IMPRESSION' | 'WEB_CONVERSION' | 'ROAS' | 'OUTBOUND_CLICK' — Optimization type for ad group delivery estimates. Supported types vary by objective. - `placement_group` 'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER' — Campaign placement group type - `product_group_ids` DeliveryEstimatesProductGroupId[] — [Targeted product group IDs](/docs/redoc/#section/AdGroup-Audience-Sizing) **Note:** This can only be combined with shopping/catalog sales campaigns. - `targeting_spec` TargetingSpecOptimal - `AGE_BUCKET` TargetingSpecAgeBucket[], nullable — **Legacy field.** Predefined age ranges. We recommend using MINIMUM_AGE and MAXIMUM_AGE instead for more flexible targeting. Cannot be combined with MINIMUM_AGE/MAXIMUM_AGE. If neither AGE_BUCKET nor MINIMUM_AGE/MAXIMUM_AGE are specified, all ages will be targeted. - `APPTYPE` TargetingSpecAppType[], nullable — Allowed devices. If the APPTYPE field is missing, the default behavior in terms of ad delivery is that **All devices/apptypes** will be targeted. - `AUDIENCE_EXCLUDE` PinterestLibIntegerFormatType[], nullable — Excluded customer list IDs. Used to drive new customer acquisition goals. For example: ["2542620905475"]. Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_EXCLUDE field is missing, the default behavior in terms of ad delivery is that **No users will be excluded**. - `AUDIENCE_INCLUDE` PinterestLibIntegerFormatType[], nullable — Targeted customer list IDs. For example: ["2542620905473"]. Audience lists need to have at least 100 people with Pinterest accounts in them Audience lists need to have at least 100 people with Pinterest accounts in them. If the AUDIENCE_INCLUDE field is missing, the default behavior in terms of ad delivery is that **All users will be included**. - `GENDER` TargetingSpecGender[], nullable — Targeted genders. Values: ["unknown","male","female"]. If the GENDER field is missing, the default behavior in terms of ad delivery is that **All genders will be targeted**. - `GEO` string[], nullable — Region codes or postal codes to include for targeting. Region codes represent broader geographical areas. Example: `US-CA` is the region code for California in the United States. Postal codes represent more granular, specific areas. Example: `94103` is a postal code for a specifc area in San Francisco, California, U.S.A. For each ad group, use only one of these methods, depending on which fits your targeting needs. Do not use both. For example, either specify a broader region code like `US-CA` or a more granular postal code within that regon, such as `94103`. You can specify multiple region codes or postal codes in an array, depending on which method you choose. Precede a region code array with the `region_codes` key and a postal code value with the `postal_codes` key. Examples: ``` "geo": { "region_codes": ["US-CA"] } ``` ``` "geo": { "postal_codes": ["94103"] } ``` For each ad group, specify at least one `GEO` or `LOCATION`. If you do not specifiy a `GEO` code, only `LOCATION` values will be targeted (See `LOCATION` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `GEO_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Region codes or postal codes to exclude from the targeting inclusion area. See `GEO` parameter in this targeting spec for rules, syntax, and other information. - `INTEREST` string[] — Array of interest object IDs. If the INTEREST field is missing, the default behavior in terms of ad delivery is that **All interests will be targeted**. - `LOCALE` string[], nullable — 24 ISO 639-1 two-letter language codes. If the LOCALE field is not included in the request, all languages are targeted. - `LOCATION` string[], nullable — Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to include for targeting. Precede country code values with the `country_codes` key and metro code values with `metro_codes` key. Example: ``` "location": { "country_codes": ["US", "CA"], "metro_codes": ["501", "602"] } ``` For each ad group, specify at least one `GEO` or `LOCATION` code. If you do not specify a `LOCATION` code, only `GEO` values will be targeted (See `GEO` parameter in this targeting spec.). Learn how to [get a current, complete list of codes](/docs/analytics-and-reports/ads-reporting/#get-all-available-codes-and-zones). - `LOCATION_EXCLUDE` string[] — [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Metropolitan codes and/or ISO-Alpha-2, two-letter country codes to exclude from targeting. See `LOCATION` parameter in this targeting spec for rules, syntax, and other information. - `MAXIMUM_AGE` string — Maximum age to target (inclusive). Values: "18", "19", ..., "65", "65+". Must be used together with `MINIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `MINIMUM_AGE` string — Minimum age to target (inclusive). Values: "18", "19", ..., "65". Note: 65+ is not allowed for minimum age. Must be used together with `MAXIMUM_AGE`. Cannot be combined with `AGE_BUCKET`. If neither `MINIMUM_AGE`/`MAXIMUM_AGE` nor `AGE_BUCKET` are specified, all ages will be targeted. - `SHOPPING_RETARGETING` TargetingSpecShoppingRetargeting[], nullable — Array of object: lookback_window [Integer]: Number of days ago to start lookback timeframe for dynamic retargeting tag_types [Array of integer]: Event types to target for dynamic retargeting exclusion_window [Integer]: Number of days ago to stop lookback timeframe for dynamic retargeting - `exclusion_window` integer — Number of days ago to stop lookback timeframe for dynamic retargeting - `lookback_window` integer — Number of days ago to start lookback timeframe for dynamic retargeting - `tag_types` integer[] — Event types to target for dynamic retargeting - `TARGETING_STRATEGY` TargetingStrategy[], nullable - `budget_duration_type` 'FIXED_DAILY' | 'FLEXIBLE_DAILY' | 'LIFETIME', required — Budget duration type for delivery estimates. - `daily_spend_cap` integer — Campaign daily spend cap. When the budget_duration_type is FIXED_DAILY or FLEXIBLE_DAILY, this field is required. - `end_date` string — End date of the date range for an ad campaign, pattern YYYY-MM-DD. Required when budget_duration_type is LIFETIME. - `lifetime_spend_cap` integer — Campaign total spending cap. When the budget_duration_type is LIFETIME, this field is required. The end date field is also required for lifetime spending. - `objective_type` 'AWARENESS' | 'CONSIDERATION' | 'CATALOG_SALES' | 'WEB_CONVERSION', required — Objective type for delivery estimates. - `start_date` string, required — Start date of the date range for an ad campaign, pattern YYYY-MM-DD. ## Response `200` The request has succeeded. - CampaignDeliveryEstimatesResponse — Delivery estimates response for a campaign. - `curves` CampaignPlanningCurveEstimate[] — Estimated curves. Each curve will pertain to a single estimation type. - `estimation_type` 'IMPRESSION' | 'CLICK' | 'CONVERSION' | 'WEEKLY_FREQUENCY' | 'WEEKLY_REACH' | 'LIFETIME_FREQUENCY' | 'LIFETIME_REACH' | 'CPM' | 'CPC' | 'CPA' — Estimation type for campaign planning estimated curve - `points` CampaignPlanningPointEstimate[] — The estimation points that make up the estimated curve. - `budget` integer, required — The budget value of the point. - `double_y` number, double, nullable, required — Y value as a decimal. - `max_y` integer, nullable, required — The maximum Y value of the point. - `min_y` integer, nullable, required — The minimum Y value of the point. - `y` integer, nullable, required — The expected Y value of the point. - `derived_metrics` CampaignDeliveryEstimatesDerivedMetrics — Derived metrics for an ad campaign. - `cpc` number, float — Estimated cost per click. - `cpc_lower` number, float — Lower estimate of the cost per click. - `cpc_upper` number, float — Upper estimate of the cost per click. - `cpm` number, float — Estimated cost per thousand impressions. - `cpm_lower` number, float — Lower estimate of cost per thousand impressions. - `cpm_upper` number, float — Upper estimate of cost per thousand impressions. - `lifetime_frequency` number, float — Estimated lifetime frequency. - `lifetime_frequency_lower` number, float — Lower estimate of lifetime frequency. - `lifetime_frequency_upper` number, float — Upper estimate of lifetime frequency. - `lifetime_impression` number, float — Estimated lifetime impressions. - `lifetime_impression_lower` number, float — Lower estimate of lifetime impressions. - `lifetime_impression_upper` number, float — Upper estimate of lifetime impressions. - `lifetime_reach` number, float — Estimated lifetime reach. - `lifetime_reach_lower` number, float — Lower estimate of lifetime reach. - `lifetime_reach_upper` number, float — Upper estimate of lifetime reach. - `weekly_click` number, float — Estimated weekly clicks. - `weekly_click_lower` number, float — Lower estimate of weekly clicks. - `weekly_click_upper` number, float — Upper estimate of weekly clicks. - `weekly_frequency` number, float — Estimated weekly frequency. - `weekly_frequency_lower` number, float — Lower estimate of weekly frequency. - `weekly_frequency_upper` number, float — Upper estimate of weekly frequency. - `weekly_impression` number, float — Estimated weekly impressions. - `weekly_impression_lower` number, float — Lower estimate of weekly impressions. - `weekly_impression_upper` number, float — Upper estimate of weekly impressions. - `weekly_reach` number, float — Estimated weekly reach. - `weekly_reach_lower` number, float — Lower estimate of weekly reach. - `weekly_reach_upper` number, float — Upper estimate of weekly reach. - `max_potential_spend` integer — Maximum potential spend estimate. ## Other responses - `400` — The request could not be understood by the server due to unexpected data. - `401` — Authentication is required and has either failed or not been provided. - `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. - `404` — The requested resource could not be found on this server. - `429` — The user has sent too many requests in a given amount of time and is being rate limited. - `503` — The service is temporarily unavailable. - `default` — An unexpected error response. --- [API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)