Google Ads: ads, keywords and negatives

Search ads, ad groups and their keywords, negative keywords and shared negative lists. 19 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_ads

Kind: read. It is marked as changing nothing.

Ads with their status, ad strength, every headline and description (with its pin and Google's performance label), final URLs, paths, approval and policy topics, what Google says to fix (action_items), and metrics, sorted by cost. A responsive display ad also shows its long headline, business name, button text and its images, each by role and asset id. A Demand Gen ad (type DEMAND_GEN_MULTI_ASSET_AD, _CAROUSEL_AD or _VIDEO_RESPONSIVE_AD) shows its texts, business name and images the same way, a video ad its long_headlines and videos and a carousel its cards, each by asset id (gads_list_assets with all_assets=true says what an asset is). ad_group_id + ad_id identify an ad for gads_set_ad_status and gads_update_ad.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	Optional campaign to list.
ad_group_id	text	no	none	Optional ad group to list.
statuses	list of one of ENABLED, PAUSED, REMOVED	no	none	Which ad statuses to include; ENABLED and PAUSED by default.
date_range	text	no	"LAST_30_DAYS"	Named range for the metrics, e.g. LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH.
start_date	text	no	none	Optional custom range start, YYYY-MM-DD (with end_date).
end_date	text	no	none	Optional custom range end, YYYY-MM-DD.
limit	whole number	no	100	Most ads to return (1-1000).
label_id	text	no	none	Only ads that carry this label (gads_list_labels).

gads_list_negative_keywords

Kind: read. It is marked as changing nothing.

Negative keywords with their match type, level and criterion id. For a campaign: its own negatives, the negatives of each of its ad groups, and the shared negative lists attached to it (gads_list_shared_negative_lists shows a list's keywords). For an ad group: its own.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	The campaign to list (give this or ad_group_id).
ad_group_id	text	no	none	The ad group to list.

gads_list_shared_negative_lists

Kind: read. It is marked as changing nothing.

Shared negative keyword lists: how many keywords each holds and which campaigns it is attached to, so it is clear what a change to one reaches. Give shared_set_id to get that list's keywords with their criterion ids as well.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
shared_set_id	text	no	none	Optional single list to show with its keywords.

gads_create_responsive_search_ad

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create a responsive search ad in an ad group. It is created PAUSED unless the installation allows new ads to start enabled; enable it with gads_set_ad_status once the user has read it. The dry run is Google's own check, policy included, so show the user what Google said.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		Ad group id (see gads_list_ad_groups).
headlines	list of AdText or text	yes		3 to 15 headlines, each up to 30 characters: a string, or {text, pinned_field} with pinned_field HEADLINE_1, HEADLINE_2 or HEADLINE_3.
descriptions	list of AdText or text	yes		2 to 4 descriptions, each up to 90 characters: a string, or {text, pinned_field} with pinned_field DESCRIPTION_1 or DESCRIPTION_2.
final_url	text	yes		The landing page, a full http(s) address.
path1	text	no	none	Optional first part of the display path, up to 15 characters.
path2	text	no	none	Optional second part; needs path1.
final_mobile_url	text	no	none	Optional separate landing page for mobile.
tracking_url_template	text	no	none	Optional tracking template.
final_url_suffix	text	no	none	Optional parameters appended to the landing page address.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_set_ad_status

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Pause or enable an ad. (Removing an ad is not supported; pausing keeps its history.)

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		The ad's ad group id.
ad_id	text	yes		Ad id from gads_list_ads.
status	one of ENABLED, PAUSED	yes		ENABLED or PAUSED.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_ad

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Change a responsive search ad's text, landing page or display path. Only what is passed changes; headlines and descriptions are each replaced as a whole list.

By default this makes a NEW ad from the old one with the changes, and the old ad is kept, so the change can be undone by hand. Where the installation creates ads paused, the new ad is PAUSED and the old one is left running: the swap is then two gads_set_ad_status calls (enable the new one, pause the old one) after the user has read the new ad. Otherwise the new ad takes the old one's status and the old one is paused, in one transaction.

in_place=true edits the ad itself instead: same id, the old text is gone from Google (it is kept only in this server's audit log), and Google reviews the ad again. Google does not say what editing in place does to the ad's statistics.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		The ad's ad group id.
ad_id	text	yes		Ad id from gads_list_ads.
headlines	list of AdText or text	no	none	New full list of 3 to 15 headlines (strings or {text, pinned_field}).
descriptions	list of AdText or text	no	none	New full list of 2 to 4 descriptions.
final_url	text	no	none	New landing page.
path1	text	no	none	New first display path; an empty string clears it.
path2	text	no	none	New second display path; an empty string clears it.
in_place	true or false	no	false	true = edit this ad rather than replace it (see above).
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_add_negative_keywords

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Add campaign-level negative keywords so ads stop showing for those searches. The result warns when a negative would block one of the campaign's own enabled keywords: show the user. Applied item by item: the answer may be partly_applied, saying which went in.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
keywords	list of KeywordInput	yes		List of {text, match_type} where match_type is EXACT, PHRASE or BROAD.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_add_ad_group_negative_keywords

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Add negative keywords to one ad group, so its ads stop showing for those searches while the campaign's other ad groups still can. Warns when one would block the ad group's own enabled keyword. Applied item by item: the answer may be partly_applied.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		Ad group id (see gads_list_ad_groups).
keywords	list of KeywordInput	yes		List of {text, match_type} where match_type is EXACT, PHRASE or BROAD.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_remove_negative_keywords

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 negative keywords from a campaign or an ad group, so ads can show for those searches again. Needs confirm_remove=true. It removes negatives only: an id that is a positive keyword, or any other kind of criterion, is refused. All or nothing.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
criterion_ids	list of text	yes		Criterion ids from gads_list_negative_keywords.
campaign_id	text	no	none	The campaign the negatives are on (give this or ad_group_id).
ad_group_id	text	no	none	The ad group the negatives are on.
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_negative_list

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 negative keyword list, optionally with its first keywords. It blocks nothing until it is attached to a campaign with gads_attach_shared_negative_list.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
name	text	yes		The list's name (unique in the account).
keywords	list of KeywordInput	no	none	Optional first keywords, {text, match_type}.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_add_to_shared_negative_list

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Add negative keywords to a shared list. They take effect in EVERY campaign the list is attached to: the result names those campaigns and warns when a negative would block one of their own enabled keywords. Applied item by item: the answer may be partly_applied.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
shared_set_id	text	yes		List id from gads_list_shared_negative_lists.
keywords	list of KeywordInput	yes		List of {text, match_type} where match_type is EXACT, PHRASE or BROAD.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_remove_from_shared_negative_list

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 keywords from a shared negative list. Ads in every campaign the list is attached to can show for those searches again. Needs confirm_remove=true. All or nothing.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
shared_set_id	text	yes		List id from gads_list_shared_negative_lists.
criterion_ids	list of text	yes		Criterion ids from gads_list_shared_negative_lists with shared_set_id.
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_attach_shared_negative_list

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Attach a shared negative keyword list to campaigns: every keyword in it becomes a negative there. Applied item by item: the answer may be partly_applied.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
shared_set_id	text	yes		List id from gads_list_shared_negative_lists.
campaign_ids	list of text	yes		The campaigns to attach it to.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_detach_shared_negative_list

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.

Detach a shared negative keyword list from campaigns: its keywords stop being negatives there, and the list itself stays. Needs confirm_remove=true. All or nothing.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
shared_set_id	text	yes		List id from gads_list_shared_negative_lists.
campaign_ids	list of text	yes		The campaigns to detach it from.
confirm_remove	true or false	no	false	Must be true, 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_create_ad_group

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Create an ad group in a Search campaign. It is created PAUSED unless the installation allows new ads to start enabled. It shows nothing until it has keywords (gads_add_keywords) and an ad (gads_create_responsive_search_ad).

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Search campaign to create it in.
name	text	yes		Ad group name (unique in the campaign).
default_cpc_bid	number	no	none	Optional default max CPC bid, in account currency.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_ad_group

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Rename an ad group, change its default max CPC bid, or pause or enable it. Only what is passed changes. (Removing an ad group is not supported; pause it.)

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		Ad group id (see gads_list_ad_groups).
name	text	no	none	New name.
default_cpc_bid	number	no	none	New default max CPC bid, in account currency.
status	one of ENABLED, PAUSED	no	none	ENABLED or PAUSED.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_add_keywords

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Add keywords to an ad group. New keywords are created PAUSED unless the server is configured otherwise. Applied item by item: the answer may be partly_applied, saying which went in.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		Target ad group id (see gads_list_ad_groups).
keywords	list of KeywordInput	yes		List of {text, match_type} where match_type is EXACT, PHRASE or BROAD.
cpc_bid	number	no	none	Optional max CPC bid in account currency; omit to use the ad group default.
status	one of ENABLED, PAUSED	no	none	PAUSED or ENABLED; leave out to follow the installation's setting.
final_url	text	no	none	Optional landing page for these keywords, instead of the ad's.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_keyword

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.

Change one keyword: pause or enable it, change its max CPC bid, its landing page or its match type, or remove it. Ids come from gads_keyword_performance. Only what is passed changes.

match_type: Google cannot change a match type in place, so this creates a NEW keyword with the same text and the new match type, carrying the old one's bid, landing page and status, and pauses the old one, in one transaction. Both ids are returned. The new keyword has no history, and it takes the old one's status even where new keywords are created paused, because it replaces a keyword a person already switched on.

remove=true deletes the keyword and its statistics for good and needs confirm_remove=true; nothing else may be passed with it. Pausing (status=PAUSED) keeps the history and can be undone: prefer it unless the user asked for the removal itself.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
ad_group_id	text	yes		Ad group id of the keyword.
criterion_id	text	yes		Keyword criterion id.
status	one of ENABLED, PAUSED	no	none	Optional new status, ENABLED or PAUSED.
cpc_bid	number	no	none	Optional new max CPC bid in account currency.
final_url	text	no	none	Optional landing page for this keyword; an empty string clears it.
match_type	one of EXACT, PHRASE, BROAD	no	none	Optional new match type: EXACT, PHRASE or BROAD (see above).
remove	true or false	no	false	true = remove the keyword (see above).
confirm_remove	true or false	no	false	Must be true with remove=true.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_update_keywords

Kind: write. It only previews the change unless dry_run is false. Not offered while the server is in read-only mode.

Pause, enable or re-bid many keywords in one call. Every keyword is read and every bid is checked against the limit before anything is sent. Applied item by item: the answer may be partly_applied, saying which went in. For a match type, a landing page or a removal, use gads_update_keyword.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
changes	list of KeywordChange	yes		List of {ad_group_id, criterion_id, status, cpc_bid}; each needs a status or a bid.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

Objects the arguments take

An argument whose type is a name takes an object with these fields.

AdText

Field	Type	Required	Default	Description
text	text (at least 1 characters)	yes		The headline or description.
pinned_field	one of HEADLINE_1, HEADLINE_2, HEADLINE_3, DESCRIPTION_1, DESCRIPTION_2	no	none	Optional position to pin it to; several texts may share one pin.

KeywordInput

Field	Type	Required	Default	Description
text	text (1 to 80 characters)	yes		Keyword text, without match-type symbols.
match_type	one of EXACT, PHRASE, BROAD	no	"PHRASE"

KeywordChange

Field	Type	Required	Default	Description
ad_group_id	text	yes		The keyword's ad group id.
criterion_id	text	yes		The keyword's criterion id.
status	one of ENABLED, PAUSED	no	none
cpc_bid	number	no	none	New max CPC bid in account currency.