Google Ads: labels, shared budgets and bulk changes
Labels, shared budgets and one change applied to many things at once. 8 tools. This page is generated from the server's own tool list, version 0.1.0, and is not edited by hand. The descriptions are the ones your AI client reads, so they are written for it. All tools lists every page.
gads_list_labels
Kind: read. It is marked as changing nothing.
The account's labels: id, name, colour and description. Give label_id to see what carries that label - the campaigns, ad groups, ads and keywords, by the ids gads_set_labels takes - so it is clear what removing it would reach. gads_campaign_performance, gads_list_ad_groups, gads_list_ads and gads_keyword_performance take a label_id to report on what carries one.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
label_id | text | no | none | Optional single label to show with what carries it. |
gads_list_budgets
Kind: read. It is marked as changing nothing.
The account's budgets: each with its daily amount, whether it is a shared budget, how many campaigns draw on it (reference_count) and which, most campaigns first. A shared budget is one amount several campaigns spend together; changing it, or moving a campaign onto or off it, changes what every campaign on it can spend.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. |
gads_create_label
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Create a label: a name, with a colour, for grouping campaigns, ad groups, ads and keywords however the user thinks of them. It changes nothing about how anything runs. Put it on things with gads_set_labels.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
name | text | yes | The label's name, up to 80 characters (unique in the account). | |
color | text | no | none | Optional background colour as #RRGGBB, e.g. #1A73E8. |
description | text | no | none | Optional short description, up to 200 characters. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_labels
Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.
Put labels on campaigns, ad groups, ads or keywords, or take labels off them. Every label named goes on (or comes off) every thing named. One or the other per call: adding is applied item by item, so the answer may be partly_applied, saying which went in; taking off is all or nothing and needs confirm_remove=true. The label itself stays (gads_remove_label removes one). A label that is already on a thing is left out of an add and said so.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
level | one of campaign, ad_group, ad, keyword | yes | campaign, ad_group, ad or keyword - what every id in ids is. | |
ids | list of text | yes | campaign ids or ad group ids; for an ad <ad_group_id>~<ad_id>; for a keyword <ad_group_id>~<criterion_id>. | |
add | list of text | no | none | Label ids (gads_list_labels) to put on them. |
remove | list of text | no | none | Label ids to take off them. |
confirm_remove | true or false | no | false | Must be true with remove, after the user asked for it. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_remove_label
Kind: write. It only previews the change unless dry_run is false. Removing needs confirm_remove to be true as well. Not offered while the server is in read-only mode.
Remove a label from the account, and with it from everything that carries it. Needs confirm_remove=true. What it was on is kept in the answer (before), since Google keeps no record of it. To take a label off some things and keep it, use gads_set_labels with remove.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
label_id | text | yes | Label id from gads_list_labels. | |
confirm_remove | true or false | no | false | Must be true, after the user asked for the removal. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_create_shared_budget
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Create a shared budget: one daily amount that several campaigns spend together. It spends nothing until a campaign is put on it with gads_set_campaign_budget. Held to this installation's highest daily budget. A budget is shared from the start or never: Google cannot turn a campaign's own budget into a shared one, or a shared one back.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
name | text | yes | The budget's name (unique in the account). | |
daily_amount | number | yes | Average daily amount in account currency units (not micros). | |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_set_campaign_budget
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Move a campaign onto another budget - usually a shared one (gads_list_budgets, gads_create_shared_budget). The move is held to this installation's limits as a change of what the campaign could spend: onto a larger budget it is a raise, checked against the highest daily budget and the largest increase in one call; onto a smaller one it always goes through. The amount of a budget is changed with gads_update_campaign_budget.
Moving a campaign onto a budget other campaigns already draw on, or off one it shares with others, changes what those campaigns can spend, so it needs allow_shared_budget=true after asking the user. A Performance Max or Demand Gen campaign and a campaign with an experiment cannot use a shared budget (Google's rule).
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
campaign_id | text | yes | The campaign to move. | |
budget_id | text | yes | The budget to put it on, from gads_list_budgets. | |
allow_shared_budget | true or false | no | false | Must be true when other campaigns share the budget it joins or leaves. |
dry_run | true or false | no | true | true = validate only (default). false = apply, only after the user confirms. |
gads_bulk_update
Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.
Pause several campaigns, ad groups, ads or keywords, or change the budget of several campaigns or the max CPC bid of several ad groups or keywords, in one call - up to 50, of any mix of levels.
Each item is read, checked and changed by itself, exactly as gads_set_campaign_status, gads_update_campaign_budget, gads_update_ad_group, gads_set_ad_status or gads_update_keyword would: the same limits, Google's own check on a dry run, and its own row in the activity log. The answer lists every item with its result or the reason it was refused; one refusal does not stop the others. Switching anything on is not offered here: status may only be PAUSED, and enabling is its own confirmed call to the single tool. A budget shared by several campaigns is refused here too: change it with gads_update_campaign_budget. For many keywords alone, gads_update_keywords is one request and one log row.
| Argument | Type | Required | Default | Description |
|---|---|---|---|---|
customer_id | text | yes | 10-digit Google Ads account id. | |
items | list of BulkItem | yes | One per thing: {"level": "campaign", "id": "111", "status": "PAUSED"}, {"level": "campaign", "id": "111", "budget": 80}, {"level": "ad_group", "id": "555", "cpc_bid": 1.2}, {"level": "ad", "id": "555~9001", "status": "PAUSED"} or {"level": "keyword", "id": "555~777", "status": "PAUSED", "cpc_bid": 0.9}. Amounts are in account currency units. | |
dry_run | true or false | no | true | true = validate every item and change nothing (default). false = make the changes, only after the user confirms. |
Objects the arguments take
An argument whose type is a name takes an object with these fields.
BulkItem
One change to one thing: a campaign's status or its budget; an ad group's or a keyword's status and bid; an ad's status.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
level | one of campaign, ad_group, ad, keyword | yes | ||
id | text | yes | campaign_id or ad_group_id; for an ad <ad_group_id>~<ad_id>; for a keyword <ad_group_id>~<criterion_id>. | |
status | text | no | none | PAUSED only. |
budget | number | no | none | Campaigns only: the new daily budget, in account currency. |
cpc_bid | number | no | none | Ad groups and keywords only: the new max CPC bid. |