Ads Manager Scripts

The AdsManagerApp class in Google Ads scripts enables you to manage accounts linked under your Manager Account. This allows you to manage all your advertiser accounts through a single script, so that you do not need to create separate scripts for each account. One popular use is running reports at the manager account level; check out our Solutions Center for other manager account use case examples.

Retrieving list of accounts

You can retrieve all accounts (except for AdWords Express accounts) under a manager account using the accounts method, e.g.:

var accountSelector = AdsManagerApp.accounts()
    .withCondition("Impressions > 100")
    .forDateRange("LAST_MONTH")
    .orderBy("Clicks DESC");

var accountIterator = accountSelector.get();

The accounts call will retrieve the list of all client accounts under the manager account hierarchy by default. You can use the withLimit method of ManagedAccountSelector class to restrict the number of accounts that your script retrieves. Another option is to select the accounts by their customer IDs using the withIds method, as shown below:

var accountSelector = AdsManagerApp.accounts()
    .withIds(['918-501-8835', '320-368-4437', '925-591-3280']);

Working on client accounts

Once you retrieve the client accounts, you can iterate through them using the ManagedAccountIterator's hasNext and next methods. You need to use the select method to switch the execution context to a client account. After you select a client account, any further API calls will apply to the client account until you explicitly select another account. For example,

// Keep track of the manager account for future reference.
var managerAccount = AdsApp.currentAccount();

// Select your accounts
...

// Iterate through the list of accounts
while (accountIterator.hasNext()) {
  var account = accountIterator.next();

  // Select the client account.
  AdsManagerApp.select(account);

  // Select campaigns under the client account
  var campaignIterator = AdsApp.campaigns().get();

  // Operate on client account
  ...
}

// Switch back to manager account
AdsManagerApp.select(managerAccount);

Working on accounts in parallel

Google Ads scripts allows you to operate on multiple client accounts in parallel, using the executeInParallel method of the ManagedAccountSelector class. The executeInParallel method has the following signature:

function executeInParallel(functionName, optionalCallbackFunctionName, optionalInput);

The executeInParallel method executes a function specified by functionName on each ManagedAccount that the ManagedAccountSelector matches. Once all accounts have been processed, the callback function, if specified by optionalCallbackFunctionName, is executed once, passing a list of ExecutionResult objects as its argument for any further processing. The typical usage is shown below:

function main() {
  var accountSelector = AdsManagerApp.accounts()
      .withLimit(50)
      .withCondition("Impressions > 100")
      .forDateRange("LAST_MONTH")
      .orderBy("Clicks DESC");

  accountSelector.executeInParallel("processClientAccount", "afterProcessAllClientAccounts");
}

function processClientAccount() {
  var clientAccount = AdsApp.currentAccount();

  // Process your client account here.
  ...

  // optionally, return a result, as a text.
  return "";
}

function afterProcessAllClientAccounts(results) {
  for (var i = 0; i < results.length; i++) {
    var result = results[i].getReturnValue();
    // Process the result further
    …
  }
}

The function specified by functionName can optionally accept a string argument (optionalInput). This parameter may be used to pass an additional parameter to all the parallel methods that is called by executeInParallel method. E.g.

function main() {
  var accountSelector = AdsManagerApp.accounts().withIds([1234567890, 3456787890]);
  var sharedParameter = "INSERT_SHARED_PARAMETER_HERE";
  accountSelector.executeInParallel("processClientAccount", null, sharedParameter);
}

function processClientAccount(sharedParameter) {
  // Process your client account here.
  ...
}

If you want to pass a JavaScript configuration object that contains account-specific settings, then you could convert it into a string using the JSON.stringify method, e.g.

function main() {
  ...
  var accountFlags = {
    '1234567890': {
       'label': 'Brand 1 campaigns',
     },
    '3456787890': {
       'label': 'Brand 2 campaigns',
     }
  };
  accountSelector.executeInParallel("processClientAccount", null,
      JSON.stringify(accountFlags));
  ...
}

function processClientAccount(sharedParameter) {
  var accountFlags = JSON.parse(sharedParameter);
  // Process your client account here.
  ...
}

The function specified by functionName can also optionally return a string. If you want to return a JavaScript object instead, you could convert it into a string using the JSON.stringify method, e.g.

function processClientAccount() {
  ...
  var jsonObj = {value: 10, list: [1,2,3,4,5,6], name: "Joe Smith"};
  return JSON.stringify(jsonObj);
}

The returned values will be passed into the callback function in a list of ExecutionResult objects. If you returned a JSON string from the function, you could convert it back into a JavaScript object using JSON.parse method, e.g.

function callbackFunctionName(results) {
  for (var i = 0; i < results.length; i++) {
    var resultObj = JSON.parse(results[i].getReturnValue());
  }
}

The executeInParallel method will operate on a maximum of 50 accounts, so you'll have to implement your own restrictions to limit the number of accounts that your script retrieves. You can use the withLimit or withIds method of ManagedAccountSelector class to restrict the number of accounts that your script retrieves.

Execution time limits

See this page for details on Ads Manager scripts execution time limits.