> [!NOTE] > **Objective:** Understand how to modify objects using the Google Ads API. As discussed in the [API structure guide](https://developers.google.com/google-ads/api/docs/concepts/api-structure), each top-level resource in the Google Ads API has a corresponding resource-type-specific service that supports modifying instances of the resource. You can also use [`GoogleAdsService.Mutate`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Mutate) to mutate multiple resource types atomically in a single request. This guide uses [`CampaignService`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignService) to demonstrate modifying [`Campaign`](https://developers.google.com/google-ads/api/reference/rpc/v26/Campaign) objects, but the same concepts apply to all other resource-type-specific services. > [!IMPORTANT] > **Key Term:** A top-level resource is a [resource](https://developers.google.com/google-ads/api/reference/rpc/v26/overview#resources) whose name does not include a period (`.`). For example, `Campaign` is a top-level resource, but `Campaign.NetworkSettings` is not. ## Mutate requests Each resource-type-specific service has a *mutate* method that accepts a mutate request. This request consists of: - A `customer_id` (or `customerId` in REST URLs) - A collection of `operations` - Optional execution settings such as `partial_failure`, `validate_only`, and `response_content_type` (which determines whether the mutable resource or only the resource name is returned after mutation) For example, the `MutateCampaigns` method of `CampaignService` accepts a [`MutateCampaignsRequest`](https://developers.google.com/google-ads/api/reference/rpc/v26/MutateCampaignsRequest) that consists of: - A `customer_id` - A collection of `CampaignOperation` objects (`operations`) - Optional execution settings (`partial_failure`, `validate_only`, and `response_content_type` indicating the preferred response type) > [!NOTE] > **Note:** Available services and methods can differ across API versions. For example, to configure customer and campaign lifecycle goals, use the `Mutate*` methods on [`GoalService`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoalService) and [`CampaignGoalConfigService`](https://developers.google.com/google-ads/api/reference/rpc/v26/CampaignGoalConfigService) in v25 and later, or the `Configure*` methods on `CustomerLifecycleGoalService` and `CampaignLifecycleGoalService` in v24 and earlier. ### Operations An operation object such as a `CampaignOperation` lets you specify the action that you want to perform on a single resource by setting its `operation` field. This field is a [`oneof` field](https://protobuf.dev/programming-guides/proto3/#oneof) consisting of the following attributes: `create` : Creates a new instance of the resource. `update` : Updates the resource to match the attributes of the `update` resource. When this field is set, you must also set the `update_mask` of the operation, which tells the Google Ads API which attributes to modify during the update operation. Each [client library](https://developers.google.com/google-ads/api/docs/client-libs) includes a field mask utility or helper method that generates the `update_mask` for you. `remove` : Removes the resource specified by its resource name string (for example, `customers/1234567890/campaigns/987654321`). Since the `operation` field is a `oneof` field, you cannot use a single operation to modify multiple objects. For example, if you want to create one campaign and remove another campaign, add two instances of `CampaignOperation` to your request: one with `create` set, and another with `remove` set. ### Batch operations Although a single operation can only either create, update, or remove a single resource, a single mutate request can contain multiple operations. You should combine your operations into a single mutate request instead of sending multiple mutate requests that each contain a single operation. For example, if you want to create ten campaigns, you should send a *single* `MutateCampaignsRequest` that has ten `CampaignOperation` objects. To group operations across different resource types into a single request, use [`GoogleAdsService.Mutate`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Mutate) or [mutating resources](https://developers.google.com/google-ads/api/docs/mutating/overview). ### Mutate responses What is returned in the response depends on what was sent in the [`response_content_type`](https://developers.google.com/google-ads/api/reference/rpc/v26/ResponseContentTypeEnum.ResponseContentType) field of the mutate request. For example, if `MUTABLE_RESOURCE` is specified, then the [response](https://developers.google.com/google-ads/api/reference/rpc/v26/MutateCampaignsResponse) contains both the resource's `resource_name` and the mutable fields of the campaign in `campaign`. By default (`RESOURCE_NAME_ONLY`), only the `resource_name` is populated in each [`MutateCampaignResult`](https://developers.google.com/google-ads/api/reference/rpc/v26/MutateCampaignResult). ### Mutate errors By default (`partial_failure = false`), the operations in a mutate request are applied to your Google Ads account only if *every* operation in the request succeeds; if any operation fails, the entire request is rolled back. For mutate requests that support partial failure (those with a `partial_failure` field on the request message), setting `partial_failure = true` commits valid operations while failed operations return operation-specific errors in the response's `partial_failure_error` field. See the [partial failure guide](https://developers.google.com/google-ads/api/docs/best-practices/partial-failures) and the [common errors guide](https://developers.google.com/google-ads/api/docs/common-errors) for details on handling errors. ## Track changes To track changes made to objects in your Google Ads account, or to retrieve the current state of objects, you can use the `change_status` and `change_event` resources. - [`change_status`](https://developers.google.com/google-ads/api/docs/change-status) provides a summary of which resources have changed within a given time period. - [`change_event`](https://developers.google.com/google-ads/api/docs/change-event) provides a detailed history of the changes, including the old and new values of the changed fields. To query these resources, use the [`GoogleAdsService.SearchStream`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/SearchStream) or [`GoogleAdsService.Search`](https://developers.google.com/google-ads/api/reference/rpc/v26/GoogleAdsService/Search) method. Read more about [report streaming using `GoogleAdsService`](https://developers.google.com/google-ads/api/docs/reporting/streaming).