Example Workflow: Putting it all together

This section walks through a series of REST calls that pause some of the campaigns in a Google Ads account that match a certain criteria. It demonstrates using the curl command line utility to send REST requests to the API.

Prerequisites

Besides having the curl command itself, you also need the following to run these commands:

A valid developer token (test access is fine)
A valid OAuth 2.0 access token for an authorized user of a Google Ads client account

Fetching specific campaigns

First, construct a Google Ads Query Language query that selects campaigns that have spent more than $1 USD on the previous day.

SELECT
  segments.date,
  campaign.name,
  campaign.status,
  metrics.cost_micros
FROM campaign
WHERE metrics.cost_micros > 1000000
  AND segments.date
DURING YESTERDAY

Next, fetch the matching campaigns using the searchStream method:

curl --request POST 'https://googleads.googleapis.com/v4/customers/1234567890/googleAds:searchStream' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'developer-token: DEVELOPER_TOKEN' \
--data-raw '{
  "query": "SELECT segments.date, campaign.name, campaign.status, metrics.cost_micros
  FROM campaign
  WHERE segments.date
  DURING YESTERDAY"
}'

Notice that you only get back the specific campaign fields requested in the query's SELECT clause. Generally, you only want to select the attributes or metrics you need for a given purpose.

[
  {
    "results": [
      {
        "campaign": {
          "resourceName": "customers/1234567890/campaigns/10987654321",
          "name": "Search Campaign 1",
          "status": "ENABLED"
        },
        "metrics": {
          "costMicros": "1320000"
        },
        "segments": {
          "date": "2020-06-10"
        }
      },
      {
        "campaign": {
          "resourceName": "customers/1234567890/campaigns/56789012345",
          "name": "Search Campaign 2",
          "status": "PAUSED"
        },
        "metrics": {
          "costMicros": "2540000"
        },
        "segments": {
          "date": "2020-06-10"
        }
      },
      {
        "campaign": {
          "resourceName": "customers/1234567890/campaigns/45678901234",
          "name": "Search Campaign 3",
          "status": "ENABLED"
        },
        "metrics": {
          "costMicros": "12630000"
        },
        "segments": {
          "date": "2020-06-10"
        }
      }
    ],
    "fieldMask": "segments.date,campaign.name,campaign.status,metrics.costMicros"
  }
]

Pausing some campaigns

To pause the resulting campaigns, you need to send operations to the campaign mutate service using the following URL:

https://googleads.googleapis.com/v4/customers/CUSTOMER_ID/campaigns:mutate

Since one of the campaigns is already PAUSED, you only need to send two operations to the service, one for each active campaign. Also, since you're only interested in updating their statuses, you can send a sparse object containing only the resourceName and new status values for each campaign:

curl --request POST 'https://googleads.googleapis.com/v4/customers/1234567890/campaigns:mutate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ACCESS_TOKEN' \
--header 'developer-token: DEVELOPER_TOKEN' \
--data-raw '{
  "operations": [
    {
      "updateMask": "campaign.status",
      "update": {
        "resourceName": "customers/1234567890/campaigns/10987654321",
        "status": "PAUSED"
      }
    },
    {
      "updateMask": "campaign.status",
      "update": {
        "resourceName": "customers/1234567890/campaigns/45678901234",
        "status": "PAUSED"
      }
    }
  ]
}'

Variations and optimization

In the preceding example, you could have specified from the start that only ENABLED campaigns be included with a campaign.status = 'ENABLED' condition in the query's WHERE clause. This would've eliminated the need to filter campaigns client-side before selectively sending some of them back in mutate operations. This would also reduce the size of the initial result set, which could lead to significant performance improvement if the number of matching campaigns is very large.

This flexibility allows you to fetch and mutate data in ways that work best for your specific use cases.

Other Methods