ad_accounts14

ad_groups13

ads10

advanced_auction2

audience_insights2

audience_sharing7

audiences4

billing11

boards11

bulk3

business_access_assets12

business_access_invite6

business_access_relationships9

campaigns8

catalog_feeds8

catalog_items3

catalog_product_groups10

catalog_reports3

catalog_supplemental7

catalogs3

conversion_deletion_requests4

conversion_eqs1

conversion_events1

conversion_tags5

conversions4

customer_list_uploads3

customer_lists4

customer_segment3

integrations7

keywords5

labels5

lead_ads4

lead_forms5

leads_export2

media3

msot_events1

notification1

oauth3

order_lines2

pins8

product_group_promotions5

product_tags3

promotions5

resources6

schedules3

search3

targeting_template3

terms2

terms_of_service1

trends4

user_account14

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."
        }
      ]
    }
  ]
}

Changes

Changed in 14 of the 29 revisions of this API.1615102

Jun 4, 2026v5b698c180678a1144See the full diff
- ▲
  added the new required request property items/id
  new-required-request-property
- ●
  removed AdGroupCommon subschema #2 from the items/ request property allOf list
  request-property-all-of-removed
- ○
  added the new optional request property items/auto_targeting_enabled
  new-optional-request-property
- ○
  added the new optional request property items/bid_in_micro_currency
  new-optional-request-property
- ○
  added the new optional request property items/bid_multiplier
  new-optional-request-property
- ○
  added the new optional request property items/bid_strategy_type
  new-optional-request-property
- ○
  added the new optional request property items/billable_event
  new-optional-request-property
- ○
  added the new optional request property items/budget_in_micro_currency
  new-optional-request-property
- ○
  added the new optional request property items/budget_type
  new-optional-request-property
- ○
  added the new optional request property items/campaign_id
  new-optional-request-property
- ○
  added the new optional request property items/customer_segment_id
  new-optional-request-property
- ○
  added the new optional request property items/end_time
  new-optional-request-property
- ○
  added the new optional request property items/ext_features
  new-optional-request-property
- ○
  added the new optional request property items/feed_profile_id
  new-optional-request-property
- ○
  added the new optional request property items/is_creative_optimization
  new-optional-request-property
- ○
  added the new optional request property items/is_local_inventory
  new-optional-request-property
- ○
  added the new optional request property items/lifetime_frequency_cap
  new-optional-request-property
- ○
  added the new optional request property items/local_inventory_radius_in_miles
  new-optional-request-property
- ○
  added the new optional request property items/name
  new-optional-request-property
- ○
  added the new optional request property items/optimization_goal_metadata
  new-optional-request-property
- ○
  added the new optional request property items/pacing_delivery_type
  new-optional-request-property
- ○
  added the new optional request property items/performance_plus_campaign_settings
  new-optional-request-property
- ○
  added the new optional request property items/placement_group
  new-optional-request-property
- ○
  added the new optional request property items/placement_traffic_type
  new-optional-request-property
- ○
  added the new optional request property items/promotion_application_level
  new-optional-request-property
- ○
  added the new optional request property items/promotion_id
  new-optional-request-property
- ○
  added the new optional request property items/promotion_ids
  new-optional-request-property
- ○
  added the new optional request property items/start_time
  new-optional-request-property
- ○
  added the new optional request property items/status
  new-optional-request-property
- ○
  added the new optional request property items/targeting_spec
  new-optional-request-property
- ○
  added the new optional request property items/targeting_spec_operations
  new-optional-request-property
- ○
  added the new optional request property items/targeting_template_ids
  new-optional-request-property
- ○
  added the new optional request property items/tracking_urls
  new-optional-request-property
- ○
  added the non-success response with the status 400
  response-non-success-status-added
- ○
  added the non-success response with the status 401
  response-non-success-status-added
- ○
  added the non-success response with the status 403
  response-non-success-status-added
- ○
  added the non-success response with the status 404
  response-non-success-status-added
- ○
  added the non-success response with the status 429
  response-non-success-status-added
- ○
  added the optional property items/items/data/auto_targeting_enabled to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/bid_multiplier to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/budget_type to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/pacing_delivery_type to the response with the 200 status
  response-optional-property-added
- ○
  added AdGroupBase to the items/items/data response property allOf list for the response status 200
  response-property-all-of-added
- ○
  removed AdGroupCommon subschema #2 from the items/items/data response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  the response property items became required for the status 200
  response-property-became-required
- ○
  the response property items/items/exceptions/items/message became required for the status 200
  response-property-became-required
This revision also has 182 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Dec 11, 2025v5537bde5a50b12See the full diff
- ▲
  the items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_EXCLUDE/items/ response property's minItems was decreased from 100 to 0 for the response status 200
  response-property-min-items-decreased
- ▲
  the items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE/items/ response property's minItems was decreased from 100 to 0 for the response status 200
  response-property-min-items-decreased
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Dec 10, 2025v56768e3ca1ffa4See the full diff
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/MAXIMUM_AGE
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/MINIMUM_AGE
  new-optional-request-property
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/MAXIMUM_AGE to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/MINIMUM_AGE to the response with the 200 status
  response-optional-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 12, 2025v58fb7ab0401592See the full diff
- ○
  added the new optional request property items/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/conversion_tag_v3_goal_metadata/reporting_event
  new-optional-request-property
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/conversion_tag_v3_goal_metadata/reporting_event to the response with the 200 status
  response-optional-property-added
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 16, 2025v543134ca41f182See the full diff
- ○
  added the new optional request property items/allOf[AdGroupCommon]/promotion_application_level
  new-optional-request-property
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/promotion_application_level to the response with the 200 status
  response-optional-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 4, 2025v510f9eba4ad9748See the full diff
- ●
  the items/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/frequency_goal_metadata/frequency request property's max was set to 20.00
  request-property-max-set
- ●
  the items/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/frequency_goal_metadata/frequency request property's min was set to 2.00
  request-property-min-set
- ●
  added the new 19+ enum value to the items/items/data/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET/items/ response property for the response status 200
  response-property-enum-value-added
- ●
  added the new 20+ enum value to the items/items/data/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET/items/ response property for the response status 200
  response-property-enum-value-added
- ○
  added the new optional request property items/allOf[AdGroupCommon]/is_creative_optimization
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/promotion_id
  new-optional-request-property
- ○
  added the new optional request property items/allOf[subschema #2]/bid_multiplier
  new-optional-request-property
- ○
  added the new 19+ enum value to the request property items/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET/items/
  request-property-enum-value-added
- ○
  added the new 20+ enum value to the request property items/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET/items/
  request-property-enum-value-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/is_creative_optimization to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/promotion_id to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[subschema #2]/bid_multiplier to the response with the 200 status
  response-optional-property-added
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Apr 23, 2024v5f9321315766f124See the full diff
- ▲
  the items/ request property type/format changed from / to object/
  request-property-type-changed
- ●
  removed the request property items/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE'
  request-property-removed
- ●
  removed the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE' from the response with the 200 status
  response-optional-property-removed
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_template_ids
  new-optional-request-property
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_template_ids to the response with the 200 status
  response-optional-property-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Feb 8, 2024v57529b464d5cb44See the full diff
- ●
  added the new DELETED_DRAFT enum value to the items/items/data/allOf[AdGroupCommon]/status/allOf[EntityStatus]/ response property for the response status 200
  response-property-enum-value-added
- ●
  added the new DELETED_DRAFT enum value to the items/items/data/allOf[subschema #2]/summary_status/allOf[AdGroupSummaryStatus]/ response property for the response status 200
  response-property-enum-value-added
- ●
  added the new DRAFT enum value to the items/items/data/allOf[AdGroupCommon]/status/allOf[EntityStatus]/ response property for the response status 200
  response-property-enum-value-added
- ●
  added the new DRAFT enum value to the items/items/data/allOf[subschema #2]/summary_status/allOf[AdGroupSummaryStatus]/ response property for the response status 200
  response-property-enum-value-added
- ○
  the request property default value ALL was added
  request-property-default-value-added
- ○
  added the new DELETED_DRAFT enum value to the request property items/allOf[AdGroupCommon]/status/allOf[EntityStatus]/
  request-property-enum-value-added
- ○
  added the new DRAFT enum value to the request property items/allOf[AdGroupCommon]/status/allOf[EntityStatus]/
  request-property-enum-value-added
- ○
  the response's property default value ALL was added for the status 200
  response-property-default-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Aug 17, 2023v50ff12596bafd11See the full diff
- ●
  added the new TWENTY_FOUR_HOUR enum value to the items/items/data/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/frequency_goal_metadata/timerange response property for the response status 200
  response-property-enum-value-added
- ○
  added the new TWENTY_FOUR_HOUR enum value to the request property items/allOf[AdGroupCommon]/optimization_goal_metadata/allOf[OptimizationGoalMetadata]/frequency_goal_metadata/timerange
  request-property-enum-value-added
May 12, 2023v5689b4b267639527See the full diff
- ▲
  added BudgetType to the items/allOf[AdGroupCommon]/budget_type request property allOf list
  request-property-all-of-added
- ▲
  removed the enum value BILLABLE_ENGAGEMENT of the request property items/allOf[AdGroupCommon]/billable_event
  request-property-enum-value-removed
- ▲
  removed the enum value CBO_ADGROUP of the request property items/allOf[AdGroupCommon]/budget_type
  request-property-enum-value-removed
- ▲
  removed the enum value DAILY of the request property items/allOf[AdGroupCommon]/budget_type
  request-property-enum-value-removed
- ▲
  removed the enum value LIFETIME of the request property items/allOf[AdGroupCommon]/budget_type
  request-property-enum-value-removed
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/APPTYPE
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_EXCLUDE
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE'
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/GENDER
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/GEO
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/INTEREST
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/LOCALE
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/LOCATION
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/SHOPPING_RETARGETING
  new-optional-request-property
- ○
  added the new optional request property items/allOf[AdGroupCommon]/targeting_spec/TARGETING_STRATEGY
  new-optional-request-property
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/AGE_BUCKET to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/APPTYPE to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_EXCLUDE to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/AUDIENCE_INCLUDE' to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/GENDER to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/GEO to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/INTEREST to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/LOCALE to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/LOCATION to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/SHOPPING_RETARGETING to the response with the 200 status
  response-optional-property-added
- ○
  added the optional property items/items/data/allOf[AdGroupCommon]/targeting_spec/TARGETING_STRATEGY to the response with the 200 status
  response-optional-property-added
- ○
  added BudgetType to the items/items/data/allOf[AdGroupCommon]/budget_type response property allOf list for the response status 200
  response-property-all-of-added
- ○
  removed the BILLABLE_ENGAGEMENT enum value from the items/items/data/allOf[AdGroupCommon]/billable_event response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the CBO_ADGROUP enum value from the items/items/data/allOf[AdGroupCommon]/budget_type response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the DAILY enum value from the items/items/data/allOf[AdGroupCommon]/budget_type response property for the response status 200
  response-property-enum-value-removed
- ○
  removed the LIFETIME enum value from the items/items/data/allOf[AdGroupCommon]/budget_type response property for the response status 200
  response-property-enum-value-removed
This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Full history (14 revisions)