Google Ads: reports, planning and experiments

The further reports, keyword ideas, forecasts and recommendations, and experiments. 15 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_account_overview

Kind: read. It is marked as changing nothing.

The whole account at a glance: every campaign that is not removed, paused ones included, with its status, channel, bidding strategy, daily budget and what it spent and converted in the last 90 days, and how many of its ad groups are enabled and paused.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.

gads_segment_report

Kind: read. It is marked as changing nothing.

Performance split one way: by device, hour of day, day_of_week, geo (country, and whether the person was in it or only interested in it), geo_region, age or gender. Each row has impressions, clicks, cost, conversions, cost per conversion and conversion rate, and the answer carries the total. Use it before changing an ad schedule, a device modifier or a location. One breakdown per call.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
segment	one of device, hour, day_of_week, geo, geo_region, age, gender	yes		device, hour, day_of_week, geo, geo_region, age or gender.
campaign_id	text	no	none	Optional campaign to report on.
ad_group_id	text	no	none	Optional ad group to report on.
date_range	text	no	"LAST_30_DAYS"	Named range such as 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.

gads_quality_score_report

Kind: read. It is marked as changing nothing.

Quality score per enabled keyword with its three components - expected click-through rate, ad relevance and landing page experience (each BELOW_AVERAGE, AVERAGE or ABOVE_AVERAGE) - and the last 30 days' impressions and cost, sorted by cost. The summary says how the scores are spread. A keyword with too little traffic has no score.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	Optional campaign to report on.
ad_group_id	text	no	none	Optional ad group to report on.
max_score	whole number	no	none	Only keywords scoring this or lower (1-10), to find the weak ones.
limit	whole number	no	200	Rows per call (1-1000).
offset	whole number	no	0	Rows to skip, for the next page.

gads_change_history

Kind: read. It is marked as changing nothing.

What was changed in the account, newest first: when, what kind of thing, created, updated or removed, each changed field with its old and new value, who did it and through what (the Google Ads website, the API, an automated rule...). Google keeps 30 days, a change can take a few minutes to appear, and changes made in Google Ads Editor are not in it.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
days	whole number	no	7	How many days back, 1 to 30.
campaign_id	text	no	none	Optional campaign to show changes for.
limit	whole number	no	200	Most changes to return (1-1000).

gads_auction_insights

Kind: read. It is marked as changing nothing.

Who else shows in the same auctions as a campaign: each competitor's impression share, how often they overlap with it, show above it, and how often it outranks them. Google gives this data only to developer tokens it has approved for it; where it refuses, the answer says so.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		Campaign id.
date_range	text	no	"LAST_30_DAYS"	Named range such as 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.

gads_pmax_report

Kind: read. It is marked as changing nothing.

A Performance Max campaign's own reports, one at a time (by): asset_group (each asset group with Google's ad strength), asset (each asset in each asset group), search_term (the searches its ads showed on - candidates for gads_add_negative_keywords, which takes a Performance Max campaign), placement (where it showed outside Search; Google gives impressions only) or channel (Search, YouTube, Display, Discover, Gmail, Maps). The answer is {rows, total_rows, more, ...}: when more is true, call again with offset = offset + returned. The other reports (gads_search_terms, gads_list_ads) have no data for Performance Max.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The Performance Max campaign's id.
by	one of asset_group, asset, search_term, placement, channel	yes		asset_group, asset, search_term, placement or channel.
date_range	text	no	"LAST_30_DAYS"	Named range such as 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	200	Rows per call (1-1000).
offset	whole number	no	0	Rows to skip, for the next page.

gads_keyword_ideas

Kind: read. It is marked as changing nothing.

Keyword ideas from Google Keyword Planner, each with its average monthly searches, how contested it is and the range of bids that reach the top of the page. Start from seed keywords, from a page's address, or both. These are estimates.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
keywords	list of text	no	none	Up to 20 seed keywords, e.g. ["erp system", "accounting software"].
url	text	no	none	A page to draw ideas from, a full http(s) address.
language_id	text	no	none	Language id from gads_search_languages (1019 Arabic, 1000 English).
geo_target_ids	list of text	no	none	Location ids from gads_search_geo_targets (2414 Kuwait, 2682 Saudi Arabia, 2818 Egypt).
include_search_partners	true or false	no	false	Count searches on Google's search partners too.
limit	whole number	no	50	Most ideas to return (default 50, at most 1000).

gads_forecast

Kind: read. It is marked as changing nothing.

Google Keyword Planner's forecast for a set of keywords bid manually: the clicks, cost, average CPC and conversions it expects over the coming days. It is Google's estimate and nothing is created. The bid and budget here are only the question asked; no limit applies.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
keywords	list of KeywordInput	yes		The keywords, each with text and match_type (EXACT, PHRASE or BROAD).
max_cpc_bid	number	yes		The most to pay for a click, in currency units.
daily_budget	number	no	none	Optional daily budget to forecast under, in currency units.
language_id	text	no	none	Language id from gads_search_languages.
geo_target_ids	list of text	no	none	Location ids from gads_search_geo_targets.
days	whole number	no	30	Length of the period, starting tomorrow (default 30, at most 365).
currency_code	text	no	none	Optional currency for the amounts; the account's own by default.

gads_recommendations

Kind: read. It is marked as changing nothing.

Google's recommendations for the account: each with its type, what it would change where that can be stated, Google's own weekly estimate with and without it, and whether gads_apply_recommendation can apply it. A recommendation is Google's suggestion, and many of them raise spend: read what one changes before applying it.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	no	none	Only this campaign's recommendations.
types	list of text	no	none	Only these types, e.g. ["CAMPAIGN_BUDGET", "KEYWORD"].
include_dismissed	true or false	no	false	Also list the ones already dismissed.
limit	whole number	no	100	Most rows to return (default 100, at most 500).

gads_list_experiments

Kind: read. It is marked as changing nothing.

The account's experiments: each with its status, dates, traffic split, the campaign it is run against, and the treatment's campaign - a draft (draft_campaign_id) until the experiment is scheduled, which is the one to change with the ordinary tools.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
include_removed	true or false	no	false	Also list removed experiments.

gads_dismiss_recommendation

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

Dismiss one of Google's recommendations, so it stops being suggested. Nothing in the account changes and nothing is spent. Google cannot check this call without doing it, so the dry run is this server's own preflight.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
recommendation_id	text	yes		From gads_recommendations.
dry_run	true or false	no	true	true = preflight only (default). false = dismiss, only after the user confirms.

gads_apply_recommendation

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

Apply one of Google's recommendations. Only the types whose effect this server can state and check: a budget recommendation (CAMPAIGN_BUDGET, FORECASTING_CAMPAIGN_BUDGET, MARGINAL_ROI_CAMPAIGN_BUDGET), a target CPA (SET_TARGET_CPA, FORECASTING_SET_TARGET_CPA) and a KEYWORD. Any other type is refused by name; make that change with its own tool.

The change is held to the same limits as making it directly (the budget cap and percent limit, the target CPA cap, the CPC bid cap), and the amount sent is the one checked: Google's recommended figure unless the call gives its own. Google cannot check this call without applying it, so the dry run is this server's own preflight, and Google may still refuse.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
recommendation_id	text	yes		From gads_recommendations.
new_daily_budget	number	no	none	Budget to apply instead of Google's figure, in currency units.
target_cpa	number	no	none	Target CPA to apply instead of Google's figure, in currency units.
cpc_bid	number	no	none	Bid for a recommended keyword instead of Google's figure, in currency units.
allow_shared_budget	true or false	no	false	Must be true to change a budget shared by several campaigns.
dry_run	true or false	no	true	true = preflight only (default). false = apply, only after the user confirms.

gads_create_experiment

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

Create an experiment on a Search campaign: the campaign as it is (control) against a changed copy (treatment), sharing its traffic and its budget. Nothing runs yet. Google makes a draft campaign for the treatment and the result gives its id: make the change under test on THAT campaign with the ordinary tools (bidding, ads, keywords...), then start the experiment with gads_schedule_experiment.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
campaign_id	text	yes		The campaign to experiment on.
name	text	yes		The experiment's name (unique in the account).
treatment_split_pct	whole number	no	50	Share of traffic the treatment gets, 1 to 99 (default 50).
suffix	text	no	"experiment"	Added to the campaign's name to name the treatment campaign.
description	text	no	none	Optional note about what is being tested.
start_date	text	no	none	Optional first day, YYYY-MM-DD. By default it starts when scheduled.
end_date	text	no	none	Optional last day, YYYY-MM-DD. By default it ends with the campaign.
dry_run	true or false	no	true	true = validate only (default). false = apply, only after the user confirms.

gads_schedule_experiment

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

Start an experiment that is in setup. Google turns the treatment's draft into a campaign that serves, and splits the base campaign's traffic with it. The treatment shares the base campaign's budget, so this adds no spend; it changes what part of the traffic sees. The call waits for Google to finish and reads its errors before it reports success.

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
experiment_id	text	yes		From gads_list_experiments or gads_create_experiment.
dry_run	true or false	no	true	true = validate only (default). false = start it, only after the user confirms.

gads_end_experiment

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

End a running experiment, or with promote=true copy the treatment onto the base campaign.

Ending stops the split: all traffic goes back to the base campaign, unchanged. Promoting makes the base campaign what the treatment was - its bidding, bids and the rest - and that is not undone from here. What promoting would write is read first and held to the same limits as making those changes directly (target CPA, bid ceiling, CPC bids).

Argument	Type	Required	Default	Description
customer_id	text	yes		10-digit Google Ads account id.
experiment_id	text	yes		From gads_list_experiments.
promote	true or false	no	false	true = apply the treatment to the base campaign. false = only end the experiment.
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.

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"