Sign in

v29

latestOpenAPI 3.0.3MITraw.githubusercontent.com2026-06-042661,1122.5 MB
ad_groups

Update ad groups

Update multiple existing ad groups.

patch/ad_accounts/{ad_account_id}/ad_groups

Path parameters

ad_account_idstring required

Unique identifier of an ad account.

Request body

auto_targeting_enabledboolean nullable

Enable auto-targeting for ad group. Default value is True. Also known as "Performance+ targeting".

bid_in_micro_currencyinteger nullable

Bid price in micro currency. This field is REQUIRED for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.

bid_multipliernumber

Open beta Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for Performance+ campaigns.

bid_strategy_type'AUTOMATIC_BID' | 'MAX_BID' | 'TARGET_AVG' | 'null' nullable

Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID, also known as "Pinterest Performance+ bidding".

billable_event'CLICKTHROUGH' | 'IMPRESSION' | 'VIDEO_V_50_MRC'

Ad group billable event type. For update, only draft ad groups may update billable event.

budget_in_micro_currencyinteger nullable

Budget in micro currency. This field is REQUIRED for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups.

budget_type'DAILY' | 'LIFETIME' | 'CBO_ADGROUP'

Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the end_time parameter is REQUIRED, and the ad group spend is spread evenly between the ad group start_time and end_time range. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. For CBO campaigns, only "CBO_ADGROUP" is allowed. For WEB_SESSIONS campaigns, only "LIFETIME" is allowed. For update, only draft ad groups may update budget type.

campaign_idstring

Campaign ID of the ad group.

customer_segment_idstring
end_timeinteger nullable

Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to paused. Cannot occur after end_time for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO.

feed_profile_idstring

Feed Profile ID associated to the adgroup.

idstring required

Ad group ID.

is_creative_optimizationboolean nullable

Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale.

is_local_inventoryboolean

Indicates whether the ad group should use the local inventory.

lifetime_frequency_capinteger

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. A CPM ad group has an IMPRESSION billable_event value. This field REQUIRES the end_time field.

local_inventory_radius_in_milesnumber

The targeting radius of the local inventory ads in miles.

namestring

Ad group name.

pacing_delivery_type'STANDARD' | 'ACCELERATED'

Ad group pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a day. When using CBO, only the STANDARD pacing delivery type is allowed.

placement_group'ALL' | 'SEARCH' | 'BROWSE' | 'OTHER'

Campaign placement group type

placement_traffic_type'ALL' | 'TWO_COLUMN_FEED' | 'FULLSCREEN_FEED' | 'null' nullable

A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both.

promotion_application_level'NONE' | 'ITEM' | 'AD_GROUP' | 'null' nullable

Specify if the promotion is applied at ad group or item level.

promotion_idstring nullable

Promotion ID. To clear this field, set to null.

promotion_idsstring[]

Promotion IDs list. To clear this field, set to an empty array [].

start_timeinteger nullable

Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's start_time. Cannot precede start_time for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO.

status'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT'

Entity status

targeting_template_idsPinterestLibIntegerFormatType[] nullable

Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0'].

Example request

[
  {
    "billable_event": "CLICKTHROUGH",
    "budget_type": "DAILY",
    "pacing_delivery_type": "STANDARD",
    "placement_group": "ALL",
    "status": "ACTIVE",
    "targeting_spec": {
      "SHOPPING_RETARGETING": [
        {
          "lookback_window": 30,
          "exclusion_window": 14,
          "tag_types": [
            0,
            6
          ]
        }
      ]
    },
    "targeting_spec_operations": [
      {
        "values": [
          {
            "lookback_window": 30,
            "exclusion_window": 14,
            "tag_types": [
              0,
              6
            ]
          }
        ]
      }
    ],
    "tracking_urls": {
      "impression": [
        "URL1",
        "URL2"
      ],
      "click": [
        "URL1",
        "URL2"
      ],
      "engagement": [
        "URL1",
        "URL2"
      ],
      "buyable_button": [
        "URL1",
        "URL2"
      ],
      "audience_verification": [
        "URL1",
        "URL2"
      ]
    }
  }
]

Response

The request has succeeded.

Example response

{
  "items": [
    {
      "data": {
        "billable_event": "CLICKTHROUGH",
        "placement_group": "ALL",
        "status": "ACTIVE",
        "targeting_spec": {
          "SHOPPING_RETARGETING": [
            {
              "lookback_window": 30,
              "exclusion_window": 14,
              "tag_types": [
                0,
                6
              ]
            }
          ]
        },
        "tracking_urls": {
          "impression": [
            "URL1",
            "URL2"
          ],
          "click": [
            "URL1",
            "URL2"
          ],
          "engagement": [
            "URL1",
            "URL2"
          ],
          "buyable_button": [
            "URL1",
            "URL2"
          ],
          "audience_verification": [
            "URL1",
            "URL2"
          ]
        }
      },
      "exceptions": [
        {
          "code": 2,
          "message": "Advertiser not found."
        }
      ]
    }
  ]
}