Documentation

Connect your marketing data to Claude, ChatGPT and other LLMs.

Tools MCP — Google Ads

81 tools exposés sur l'endpoint https://gadspilot.com/mcp. Cliquez sur un tool pour voir ses paramètres.

💡
Vous n'avez jamais besoin d'appeler ces tools manuellement — posez votre question en français à Claude/ChatGPT/Cursor, le LLM choisit le bon tool, gère les paramètres et résume la réponse. Cette doc liste juste ce qui est disponible.

📊 Reporting & Insights (21)

get_campaign_performance Read
Campaign metrics for a date range.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_ad_group_performance Read
Ad group level metrics.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_keyword_performance Read
POSITIVE keywords ONLY by default — with quality score, ad_group.status (= status of the parent group, key to detect "ENABLED keyword in PAUSED group" traps), keyword status, metrics (primary `conversions` + total `all_conversions` for full visibility on secondary actions like Begin_Checkout). Each row is also annotated with effectively_blocked_by[] listing negatives that would block matching queries (and is_blocked boolean). ⚠ Negatives are EXCLUDED by default — they have no performance, they are exclusions. To list negatives, use the dedicated list_negative_keywords tool (unified view of the 4 mechanisms). Pass include_negatives=true ONLY if you specifically need them merged in (rare).
Parameters
date_range * string Date range shortcut.
campaign_id string
ad_group_id string
min_impressions integer
include_negative_check boolean Default true. Set false to skip the negative cross-check annotation (faster).
include_negatives boolean Default false. If true, negative keywords are returned MERGED with positives (with negative=true flag) — usually you want list_negative_keywords instead.
get_search_terms Read
Actual search queries triggering ads, cross-referenced with configured keywords.
Parameters
date_range * string Date range shortcut.
campaign_id string
ad_group_id string
min_cost_micros integer
sort_by string
get_ad_performance Read
RSA ad performance with ad strength and assets.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_geographic_report Read
Performance by country, region, or city. Returns geographic_view.country_criterion_id (numeric Google geo ID).
Parameters
date_range * string Date range shortcut.
campaign_id string
ad_group_id string
level string
get_device_report Read
Performance split by device (MOBILE, DESKTOP, TABLET).
Parameters
date_range * string Date range shortcut.
campaign_id string
get_hourly_report Read
Performance by hour of day and/or day of week.
Parameters
date_range * string Date range shortcut.
segment_by string
campaign_id string
get_auction_insights Read
Impression share vs competitors.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_impression_share Read
Impression share lost to budget vs rank.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_budget_pacing Read
Daily budget vs actual spend with pacing analysis.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_change_history Read
All account changes with before/after values (Google Ads change_event resource, max 30 days history). RECOMMENDED: keep resource_type=ALL unless you specifically need to filter — narrow filters often miss related changes (ex: filter=CAMPAIGN misses CAMPAIGN_CRITERION which is what changes when you edit targeting / shared sets / negatives on a campaign).
Parameters
date_range * string Date range shortcut.
campaign_id string
resource_type string
get_pmax_performance Read
Performance Max campaign details.
Parameters
date_range * string Date range shortcut.
campaign_id string
get_recommendations Read
Google native optimization recommendations.
Parameters
get_conversion_tracking_settings Read
Customer-level conversion tracking settings (read-only). Returns conversion_tracking_id, conversion_tracking_status, accepted_customer_data_terms, enhanced_conversions_for_leads_enabled, cross_account_conversion_tracking_id, google_ads_conversion_customer. Note: enhanced_conversions_for_leads_enabled is OUTPUT_ONLY in the Google Ads API — to toggle it, the user must use the Google Ads UI (Tools → Conversions → Settings).
Parameters
get_conversions_by_action Read
Conversions broken down BY conversion_action over a date range. Returns conversions, conversions_value, all_conversions, all_conversions_value, view_through_conversions per action — essential to diagnose a high all_conv/conv ratio (which conversion action is over-credited via view-through?) and to see per-action volume without aggregating across all actions. Optional campaign_id filter.
Parameters
date_range * string
campaign_id string
get_account_targets Read
Get gadspilot LOCAL business targets (CPA / ROAS / monthly budget cap) — these are the user's OWN objectives stored in gadspilot's own database, used ONLY by the AI for analytical contextualization. ⚠ NOT TO BE CONFUSED WITH Google Ads' native bidding targets (the `target_cpa_micros` / `target_roas` params used in TARGET_CPA / TARGET_ROAS bidding strategies via update_bidding_strategy or create_search_campaign — those are sent to Google to drive the auction algorithm). gadspilot Targets are NEVER pushed to Google Ads, NEVER affect the bidding strategy, NEVER appear in the Google Ads UI. They exist purely so the AI can say "your CPA is €42 vs your €25 target = 68% over" instead of using generic industry benchmarks. Returns account_defaults + per-campaign overrides. If empty for a campaign, inherit the account default. If has_any_target is false, no business goal is set — answer without target comparison.
Parameters
campaign_id string Optional — restrict the campaign overrides to one specific campaign.
get_responsive_search_ads Read
List Responsive Search Ads with headlines, descriptions, paths, final URLs and ad strength. Filterable by campaign / ad group / status.
Parameters
campaign_id string
ad_group_id string
status string
get_account_summary Read
Top-level account KPIs for a date range.
Parameters
date_range * string Date range shortcut.
get_account_budget_summary Read
All campaign budgets with spend and pacing.
Parameters
date_range * string Date range shortcut.
get_audience Read
Get full details of one audience (dimensions, exclusion_dimension, status, member_count). Use after list_audiences to inspect an audience before attaching as PMax signal.
Parameters
audience_id * string

🏗 Structure & Listing (9)

list_accounts Read
List all Google Ads accounts accessible with this token.
Parameters
list_campaigns Read
List all campaigns with status and basic config.
Parameters
status string
type string
list_negative_keywords Read
List all negative keywords (campaign-level and ad-group-level) for the account or for a specific campaign/ad group. Returns separate arrays for campaign_negatives and ad_group_negatives with text + match_type.
Parameters
campaign_id string
ad_group_id string
list_conversion_actions Read
List all conversion actions with their status, type, category, primary_for_goal flag, value settings, and attribution model. Essential for audit start.
Parameters
status string
list_campaign_locations Read
List all LOCATION criteria of campaign(s) — geographic targeting (countries, regions, cities), with negative flag and bid_modifier. Use this before any geo write operation.
Parameters
campaign_id string
list_ad_groups Read
Lightweight skeleton view of ad groups across the account. For EACH group returns : ad_group_id, name, status, type, campaign_id + name + status, dormant flag (= group ENABLED but campaign NOT ENABLED → never serves, common confusion), keywords_count_active / paused / negatives, cost_30d_eur, conversions_30d. ONE call = complete account map without the verbosity of get_ad_group_performance. Use this BEFORE diving into specific ad group analysis — it tells you which groups are real (active in active campaign) vs dormant (orphans that never serve) vs paused.
Parameters
campaign_id string Optional — restrict to one campaign.
status string Optional — only ENABLED or only PAUSED groups (REMOVED always excluded).
list_shared_sets Read
List shared sets (negative keyword lists, brand exclusions, placement exclusions) on this account. Optional filter by type. Returns id + name + member_count + reference_count (number of campaigns linked).
Parameters
type string
list_shared_set_criteria Read
List all criteria (keywords/placements) inside a given shared set. Use list_shared_sets first to find the shared_set_id.
Parameters
shared_set_id * string
list_audiences Read
List audiences available on this account (custom segments, in-market, affinity, customer_match, etc.) — use to discover audience_ids before attaching them as PMax signals via asset_group_signal_add.
Parameters
status string Default ENABLED — only active audiences.

✏️ Write actions (46)

All default to dry-run mode

set_account_targets Write · dry-run
Set the gadspilot LOCAL business Targets at the ACCOUNT default level (CPA / ROAS / monthly budget cap). ⚠ These are gadspilot's OWN local objectives used for AI contextualization — they are NEVER pushed to Google Ads and NEVER affect bidding (different from update_bidding_strategy). Pass null on a field to clear it. Pass nothing for a field to leave it unchanged. At least one field must be provided. Targets persist across MCP sessions and are used by both the in-app AI chat and every future MCP analysis. To set per-campaign overrides, use set_campaign_targets instead. To READ current values use get_account_targets.
Parameters
target_cpa_eur number|null Account-default target CPA in EUR. Pass null to clear. Range: 0–100000.
target_roas number|null Account-default target ROAS (e.g. 2.5 = 250%). Pass null to clear. Range: 0–99.99.
monthly_budget_max_eur number|null Monthly hard budget ceiling in EUR — used by the AI to flag overspend risk before any write that would push you over. Pass null to clear. Range: 0–10000000.
dry_run boolean
set_campaign_targets Write · dry-run
Bulk upsert gadspilot LOCAL per-campaign Target overrides (CPA + ROAS). Each entry overrides the account default for ONE campaign. ⚠ Same scope as set_account_targets — local to gadspilot, NEVER pushed to Google, NEVER affects bidding. To CLEAR an override (= make the campaign inherit the account default again), pass both target_cpa_eur and target_roas as null/0 for that campaign's entry. Useful for batch ops like "set CPA=15 on all brand campaigns" via a single call. Returns counts of updated + deleted overrides.
Parameters
overrides * array List of per-campaign overrides. Each item must have campaign_id; both target_cpa_eur and target_roas null/0 → deletes the override.
dry_run boolean
create_search_campaign Write · dry-run
Create a Search campaign. EU REGULATION : since end of 2024, every campaign targeting EU countries (FR, BE, LU, NL, DE, ES, IT, ...) must declare whether it contains political advertising or not. Default contains_eu_political_advertising=false (commercial campaigns) — only set true for actual political ads (which require additional Google verification).
Parameters
name * string
daily_budget_micros * integer
bidding_strategy * string
target_cpa_micros integer
target_roas number
cpc_bid_ceiling_micros integer For MAXIMIZE_CLICKS / TARGET_SPEND only.
geo_target_ids array
language_ids array
contains_eu_political_advertising boolean EU political advertising declaration (required by Google for EU-targeting campaigns since end of 2024). Default false. Set true ONLY for genuine political ads.
dry_run boolean
create_ad_group Write · dry-run
Create an ad group inside an existing campaign.
Parameters
campaign_id * string
name * string
cpc_bid_micros integer
dry_run boolean
update_ad_group_status Write · dry-run
Pause or re-enable an ENTIRE ad group in one call without touching ads or keywords. Avoids the lossy hack of pausing all ads + removing all keywords (which destroys performance history irreversibly). Status REMOVED requires a separate remove operation and is irreversible.
Parameters
ad_group_id * string
status * string
dry_run boolean
rename_ad_group Write · dry-run
Rename an ad group. The new name must be unique within the campaign (Google Ads rejects DUPLICATE_AD_GROUP_NAME otherwise) and ≤ 255 characters. Useful for cleanup (typos, naming convention enforcement).
Parameters
ad_group_id * string
new_name * string
dry_run boolean
update_keyword_bid Write · dry-run
Set the CPC bid (in micros) on one or more keywords (ad_group_criterion). Single mode : ad_group_id + criterion_id + cpc_bid_micros. Batch mode : keywords[] of {ad_group_id, criterion_id, cpc_bid_micros}. Use this to boost top performers (+50% on a keyword that converts) without touching campaign-level bidding strategy. To get criterion_id, query GAQL "SELECT ad_group_criterion.criterion_id, ad_group_criterion.keyword.text FROM ad_group_criterion WHERE ad_group_criterion.type = KEYWORD".
Parameters
ad_group_id string Single mode only.
criterion_id string Single mode only.
cpc_bid_micros integer Single mode only. New CPC bid in micros (1€ = 1000000).
keywords array Batch mode. Each item: {ad_group_id, criterion_id, cpc_bid_micros}.
dry_run boolean
bulk_update_keyword_status Write · dry-run
Pause or re-enable multiple keywords in ONE call WITHOUT removing them — preserves performance history (vs bulk_remove_criteria which is permanent and loses everything). Aligned with the "pause before removing" safety philosophy. status REMOVED is forbidden — for that use bulk_remove_criteria explicitly. Single mode : ad_group_id + criterion_id. Batch mode : keywords[] of {ad_group_id, criterion_id}.
Parameters
status * string
ad_group_id string Single mode only.
criterion_id string Single mode only.
keywords array Batch mode. Each item: {ad_group_id, criterion_id}.
dry_run boolean
create_rsa_ad Write · dry-run
Create a Responsive Search Ad. Headlines & descriptions accept either a plain string or an object {text, pinnedField} where pinnedField is HEADLINE_1/2/3 (headlines) or DESCRIPTION_1/2 (descriptions). Optional final_url_suffix and url_custom_parameters [{key, value}] for tracking.
Parameters
ad_group_id * string
headlines * array 3 to 15 headlines, max 30 chars each. Each item is either a plain string or {text, pinnedField}.
descriptions * array 2 to 4 descriptions, max 90 chars each. Each item is either a plain string or {text, pinnedField}.
final_url * string Landing page URL (https://…).
path1 string Display URL path 1 (max 15 chars).
path2 string Display URL path 2 (max 15 chars).
final_url_suffix string Tracking suffix appended to the final URL (e.g. "cpurl={_cpurl}").
url_custom_parameters array Custom URL parameters used by ValueTrack {_xxx} tokens.
dry_run boolean
create_display_ad Write · dry-run
Create a Responsive Display Ad (RDA) — the only servable Display format since 2022 (legacy Image / Expanded Text Ads are deprecated). The ad_group must belong to a Display or Discovery campaign. Required: 1-5 short headlines (≤30 char), 1 long_headline (≤90 char), 1-5 descriptions (≤90 char), 1 business_name (≤25 char), final_url, and at least ONE image set (landscape 1.91:1 via marketing_image_urls OR square 1:1 via square_marketing_image_urls). Images are auto-fetched from URL and uploaded as Assets (JPG/PNG, ≤5MB each). Created PAUSED — use enable_ad to activate after review.
Parameters
ad_group_id * string
headlines * array 1-5 short headlines, ≤30 char each.
long_headline * string Single long headline, ≤90 char.
descriptions * array 1-5 descriptions, ≤90 char each.
business_name * string
final_url * string Landing page URL.
marketing_image_urls array Landscape images 1.91:1 (recommended 1200x628). At least one required if no square images.
square_marketing_image_urls array Square images 1:1 (recommended 1200x1200). Required if no landscape.
logo_image_urls array Landscape logos 4:1 (optional).
square_logo_image_urls array Square logos 1:1 (optional).
call_to_action_text string Optional CTA text override (Google may auto-pick if omitted).
allow_flexible_color boolean Default true — Google can adjust colors for placement.
dry_run boolean
enable_ad Write · dry-run
Re-enable a paused ad (symmetric of pause_ad). Works on RSA, Display, Video. Cannot revive a REMOVED ad — for that use create_rsa_ad / create_display_ad. Pass ad_group_ad_id in format "ad_group_id~ad_id" (same format as pause_ad).
Parameters
ad_group_ad_id * string Format "ad_group_id~ad_id".
dry_run boolean
update_rsa_ad Write · dry-run
Update URL-related fields of an existing Responsive Search Ad without having to pause + recreate. ⚠ Google Ads API does NOT allow mutating headlines, descriptions, path1 or path2 on an existing ad — those fields are immutable once the ad is created. For creative changes, use create_rsa_ad + pause_ad on the old one. THIS tool only patches: final_urls, final_mobile_urls, tracking_url_template, final_url_suffix, url_custom_parameters, name. Pass ad_id (the standalone Ad resource ID, NOT ad_group_ad). At least one mutable field is required ; FieldMasks::allSetFieldsOf only patches what you pass.
Parameters
ad_id * string Standalone Ad resource ID (the second part of an ad_group_ad ID like "ad_group_id~ad_id").
final_urls array New landing page URLs. Replaces the existing list.
final_mobile_urls array
tracking_url_template string
final_url_suffix string
url_custom_parameters array Custom URL parameters used by ValueTrack {_xxx} tokens. Replaces the existing list.
name string Internal ad name (display only, not the ad creative).
dry_run boolean
add_keywords Write · dry-run
Add keywords to an ad group.
Parameters
ad_group_id * string
keywords * array
dry_run boolean
add_negative_keywords Write · dry-run
Add negative keywords at campaign or ad group level (Search campaigns). For Performance Max campaigns, use shared_set_criterion_add instead — PMax doesn't support direct campaign-level negatives, only via shared sets.
Parameters
level * string
campaign_id * string
ad_group_id string
keywords * array
dry_run boolean
shared_set_create Write · dry-run
Create a new shared set (negative keywords list, brand exclusion list, placement exclusion list). After creating, use campaign_shared_set_link to attach it to one or more campaigns. Required for PMax negative management.
Parameters
name * string
type * string
dry_run boolean
shared_set_criterion_add Write · dry-run
Add criteria to a shared set. Pass keywords[] for NEGATIVE_KEYWORDS sets (PMax + Search), placements[] for NEGATIVE_PLACEMENTS sets (PMax exclusive way to block sites/apps). The criteria apply to ALL campaigns this shared set is linked to.
Parameters
shared_set_id * string
keywords array For NEGATIVE_KEYWORDS shared sets only.
placements array For NEGATIVE_PLACEMENTS shared sets only. type=url → website domain (ex: "jecontacte.com"), type=app → mobile app id (ex: "android-com.truecaller.android" or "ios-12345").
dry_run boolean
shared_set_criterion_remove Write · dry-run
Remove criteria from a shared set by their criterion_ids. Use list_shared_set_criteria first to get the IDs.
Parameters
shared_set_id * string
criterion_ids * array
dry_run boolean
add_positive_locations Write · dry-run
POSITIVELY target countries/regions/cities on a campaign (vs add_negative_locations which excludes). Use this to focus on FR/BE/LU instead of excluding 200 countries one by one. Pass geo_target_constant IDs (e.g. 2250 = France, 2056 = Belgium).
Parameters
campaign_id * string
country_criterion_ids * array
dry_run boolean
add_audience_to_ad_group Write · dry-run
Attach an audience to an ad group as targeting (observation / bid-adjusted) OR exclusion. Pass exactly ONE audience source: user_list_id (remarketing / customer match / similar audiences), custom_audience_id (custom segments built via custom_audience_create), or audience_id (the newer unified Audience resource). For TARGETING : bid_modifier 1.0 = observation only (default), 1.2 = +20% bid, 0.8 = -20%, range 0.1-10.0. For EXCLUSION : pass negative=true (typical use case : exclude GA4 Purchasers from acquisition campaigns, or recent visitors from conquest). bid_modifier ignored when negative=true. To get user_list_id values: GAQL "SELECT user_list.id, user_list.name FROM user_list". To get audience_id: list_audiences.
Parameters
ad_group_id * string
user_list_id string Remarketing / Customer Match / Similar audiences user list ID.
custom_audience_id string Custom audience ID (created via custom_audience_create / interests / URL seeds).
audience_id string Audience resource ID (newer Audience API).
bid_modifier number Float 0.1-10.0. Default 1.0 (observation, no bid change). Ignored when negative=true.
negative boolean If true, attach as EXCLUSION instead of targeting. Default false.
dry_run boolean
set_campaign_languages Write · dry-run
Set the languages of a campaign in REPLACE mode — final state = exactly the language_ids passed. Computes diff: removes existing languages not in target, adds missing ones, no-op if already aligned. Use this to fix campaigns that ended up with "All languages" (default) when you want only French (1002) or English (1000). Pass language_constant IDs (1002=FR, 1000=EN, 1003=ES, 1001=DE, 1014=NL, 1019=IT). Pass [] to clear all (= "All languages").
Parameters
campaign_id * string
language_ids * array List of language_constant IDs. Pass empty array to remove all language criteria (Google Ads default = All languages).
dry_run boolean
add_negative_placements Write · dry-run
Block placements (Display sites, mobile apps, YouTube videos/channels) on a campaign. AUTO-DETECTS PERFORMANCE_MAX: PMax rejects direct campaign-level placement criteria (OPERATION_NOT_PERMITTED_FOR_CONTEXT), so for PMax this tool transparently routes through a NEGATIVE_PLACEMENTS shared set (find-or-create "gadspilot — PMax negative placements" by default, then add criteria + link to the campaign). YouTube video/channel exclusions are NOT supported via shared set on PMax — use brand exclusions for that. Pass shared_set_name to override the auto-named set, or shared_set_id to reuse a specific existing one.
Parameters
campaign_id * string
urls array Display network site URLs (ex: ["jecontacte.com", "glance.com"])
app_ids array Mobile app IDs in format "android-com.example.app" or "ios-12345"
youtube_video_ids array YouTube video IDs (the v=XXX in the URL). NOT supported on PMax campaigns.
youtube_channel_ids array YouTube channel IDs (UCxxx). NOT supported on PMax campaigns.
shared_set_id string PMax-only override : reuse this shared_set_id instead of find-or-create.
shared_set_name string PMax-only override : custom name for the shared set on auto-create (default "gadspilot — PMax negative placements").
dry_run boolean
asset_group_signal_add Write · dry-run
Add a search theme OR audience signal to a PMax asset group. CRITICAL for PMax — these are the only "targeting" signals you give the algorithm. Without them, PMax runs blind. To find asset_group_id, use list_campaigns then look at the campaign in PMax. To find audience_id, use the existing audience_list workflow (or paste the resource_name from /accounts/{id}/insights tab "PMax signals").
Parameters
asset_group_id * string
type * string
value * string For SEARCH_THEME: the theme text (ex: "VPS hosting providers"). For AUDIENCE: the audience_id (ex: "12345") OR full resource_name (ex: "customers/X/audiences/Y").
dry_run boolean
asset_group_signal_remove Write · dry-run
Remove an asset_group_signal by its resource_name. Get the resource_name from a previous asset_group_signal_add response or from list-style queries on asset_group_signal.
Parameters
resource_name * string Full resource name (ex: "customers/X/assetGroupSignals/AG_ID~SIG_ID")
dry_run boolean
ad_schedule_set Write · dry-run
Set the ad schedule (days of week + hours) of a campaign. Useful for B2B campaigns to only run lun-ven 9h-19h. By default REPLACES all existing schedules — set replace=false to ADD without removing.
Parameters
campaign_id * string
schedules * array
replace boolean Default true — wipes existing schedules first
dry_run boolean
asset_group_asset_add Write · dry-run
Link an existing asset (text, image, video, logo) to a PMax asset group with a specific field_type. Asset must already exist (created via UI or asset_create). Useful for refreshing PMax creas without UI.
Parameters
asset_group_id * string
asset_id * string
field_type * string
dry_run boolean
asset_group_asset_remove Write · dry-run
Unlink an asset from a PMax asset group (preserves the asset itself). Need the same triplet (asset_group_id, asset_id, field_type) used at creation.
Parameters
asset_group_id * string
asset_id * string
field_type * string
dry_run boolean
update_inventory_type Write · dry-run
NOT_IMPLEMENTED stub — Google Ads API does NOT expose a campaign-level toggle "exclude mobile apps" / "exclude in-app inventory". This tool returns guidance pointing to the real solution: use add_negative_placements with specific app_ids OR create a shared NEGATIVE_PLACEMENTS list. Documented for transparency — Claude should NOT use this, fall back to the recommended alternative.
Parameters
campaign_id * string
exclude array
dry_run boolean
remove_negative_keywords Write · dry-run
Remove negative keywords at campaign or ad group level (Search campaigns). High-level convenience wrapper : pass criterion_ids (returned by list_negative_keywords) instead of full resource_names. For PMax shared list negatives, use shared_set_criterion_remove instead. Symmetric counterpart of add_negative_keywords.
Parameters
level * string
campaign_id string Required when level=CAMPAIGN.
ad_group_id string Required when level=AD_GROUP.
criterion_ids * array List of criterion_ids to remove. Get them from list_negative_keywords.
dry_run boolean
bulk_remove_criteria Write · dry-run
Power-tool : remove N criteria across campaigns/ad-groups/shared-sets in one batched call. Auto-routes per resource_name prefix (CampaignCriterion / AdGroupCriterion / SharedCriterion). For typical use, prefer the friendlier remove_negative_keywords (campaign/ad-group negatives) or shared_set_criterion_remove (PMax shared lists).
Parameters
resource_names * array Full resource names of criteria to remove (ex: "customers/X/campaignCriteria/CAMPAIGN~CRIT_ID")
dry_run boolean
conversion_action_create Write · dry-run
Create a conversion action (= goal) on the account (Purchase, Lead, Signup, Submit Lead Form, etc.). Use type=WEBPAGE for website tags, UPLOAD_CLICKS/CALLS for offline imports. Optional default_value for value-based bidding.
Parameters
name * string
type * string
category * string
default_value number Optional — for value-based bidding. EUR amount.
always_use_default_value boolean If true, override the value passed by gtag/code with default_value.
dry_run boolean
conversion_action_update Write · dry-run
Update an existing conversion action (status, name, default_value). Use list_conversion_actions to find the conversion_action_id.
Parameters
conversion_action_id * string
name string
status string
default_value number
always_use_default_value boolean
dry_run boolean
asset_create Write · dry-run
Create an asset (text / image / youtube_video) at account level. After creation, link to a PMax asset group via asset_group_asset_add. For images: pass image_url, the API downloads (max 5MB, JPG/PNG).
Parameters
type * string
name string Optional — display name for the asset
text string Required if type=TEXT
image_url string Required if type=IMAGE — fetch URL
youtube_video_id string Required if type=YOUTUBE_VIDEO — the v=XXX from YouTube URL
dry_run boolean
create_custom_audience Write · dry-run
Create a Google Ads custom audience (= custom segment) from URLs (competitor sites) and/or search keywords (search intentions). Useful for PMax: create "Concurrents Dokploy" with urls=[heroku.com, vercel.com], then attach via asset_group_signal_add(type=AUDIENCE). Google needs ~24h to validate before the audience is usable as a PMax signal.
Parameters
name * string
description string
urls array Competitor / similar sites URLs
keywords array Search intent keywords
dry_run boolean
update_campaign_budget Write · dry-run
Change a campaign's daily budget.
Parameters
campaign_id * string
new_budget_micros * integer
dry_run boolean
update_campaign_status Write · dry-run
Enable or pause a campaign.
Parameters
campaign_id * string
status * string
dry_run boolean
rename_campaign Write · dry-run
Rename a campaign. The new name must be unique within the account (Google Ads rejects DUPLICATE_CAMPAIGN_NAME otherwise) and ≤ 255 characters. Works on all channel types (Search, Display, PMax, Video, Shopping).
Parameters
campaign_id * string
new_name * string New campaign name (≤ 255 char, must be unique in the account).
dry_run boolean
update_campaign_networks Write · dry-run
Toggle the network distribution of a campaign (Google Search, Search partners, Display, YouTube, Google TV). Each toggle is optional — only the ones explicitly passed are modified, others left as-is. Most common use : Search campaigns are created with Display ON by default in Google Ads UI ; pass target_content_network=false to opt out of Display without touching Search/Search partners. Mappings to UI labels : target_google_search="Google Search", target_search_network="Search partners", target_content_network="Display Network".
Parameters
campaign_id * string
target_google_search boolean Show on Google Search results page.
target_search_network boolean Show on Google Search partners (other sites that use Google search).
target_content_network boolean Show on Display Network. Set false to opt out of Display on a Search campaign.
target_youtube boolean
target_google_tv_network boolean
dry_run boolean
update_bidding_strategy Write · dry-run
Change campaign bidding strategy. ⚠ The `target_cpa_micros` / `target_roas` params here are GOOGLE ADS bidding signals — sent to Google's auction algorithm to drive bids. NOT to be confused with gadspilot LOCAL Targets (get_account_targets) which are the user's business goals stored locally for AI contextualization only and have NO impact on bidding. ⚠ PMAX SPECIFIC : Performance Max campaigns do NOT accept TARGET_CPA or TARGET_ROAS as direct bidding strategies — the API rejects. To set a target CPA on PMax, use bidding_strategy=MAXIMIZE_CONVERSIONS + target_cpa_micros. To set a target ROAS on PMax, use bidding_strategy=MAXIMIZE_CONVERSION_VALUE + target_roas. MAXIMIZE_CLICKS (also accepted as TARGET_SPEND, the underlying API name) is for Search/Display only — common for new campaigns or transitions, optionally with cpc_bid_ceiling_micros to cap the per-click bid. For Search/Display, all 6 strategies work directly.
Parameters
campaign_id * string
bidding_strategy * string
target_cpa_micros integer For TARGET_CPA (Search/Display) OR MAXIMIZE_CONVERSIONS (PMax-compatible). Ex: 25000000 = €25 target CPA.
target_roas number For TARGET_ROAS (Search/Display) OR MAXIMIZE_CONVERSION_VALUE (PMax-compatible). Ex: 2.5 = 250% ROAS.
cpc_bid_ceiling_micros integer For MAXIMIZE_CLICKS / TARGET_SPEND only — optional CPC ceiling cap (in micros).
dry_run boolean
pause_ad Write · dry-run
Pause a specific ad.
Parameters
ad_group_ad_id * string Format: ad_group_id~ad_id
dry_run boolean
remove_ad Write · dry-run
Permanently remove (soft-delete) a specific ad. Sets the ad status to REMOVED — Google Ads has no DELETE operation for ads. This is IRREVERSIBLE: the ad cannot be re-enabled, only re-created from scratch. Use pause_ad if you may want to re-enable later.
Parameters
ad_group_ad_id * string Format: ad_group_id~ad_id (e.g. 10719290410~806542107985)
dry_run boolean
add_negative_locations Write · dry-run
Exclude N countries/regions from a campaign in one call. country_criterion_ids are Google geo target constants (e.g. 2250=France, 2384=Côte d'Ivoire, 2466=Mali). Get IDs from https://developers.google.com/google-ads/api/reference/data/geotargets. Detects automatically if a country is already targeted POSITIVELY on this campaign (Google Ads forbids same location being both positive and negative): without `replace_existing` returns a structured CONFLICT_POSITIVE_EXISTS error listing the criterion_ids; with `replace_existing=true` removes the positive criteria and creates the negative ones in a single atomic batch.
Parameters
campaign_id * string
country_criterion_ids * array Array of Google geo target constant IDs to exclude.
replace_existing boolean Default false. If true, automatically removes any existing POSITIVE criterion on these countries before creating the negative ones (atomic). Use when the user explicitly wants to flip a country from positive targeting to exclusion.
dry_run boolean
set_location_bid_modifier Write · dry-run
Set bid modifier for a single country/region on a campaign. bid_modifier 1.0=no change, 1.30=+30%, 0.80=-20%, 0.50=-50%. Range: 0.1 to 10.0. If criterion already exists it is updated, otherwise created.
Parameters
campaign_id * string
country_criterion_id * integer Google geo target constant ID.
bid_modifier * number
dry_run boolean
set_location_bid_modifiers_batch Write · dry-run
Apply multiple location bid modifiers in one call. modifiers is an object {country_criterion_id: bid_modifier}.
Parameters
campaign_id * string
modifiers * object Object mapping country_criterion_id (string key) to bid_modifier (number).
dry_run boolean
remove_location_criterion Write · dry-run
Remove a location criterion (negative or positive) from a campaign. criterion_id is the campaign_criterion criterion_id (NOT the geo target id) — get it from list_campaign_locations first.
Parameters
campaign_id * string
criterion_id * integer campaign_criterion.criterion_id from list_campaign_locations.
dry_run boolean

🧠 Persistent memory (3)

Notes + change log shared across sessions

get_local_change_log Read
Returns gadspilot's own write history for this account (every write tool call ever made via gadspilot, with parameters + result). Persistent across sessions. Use this BEFORE making changes to know what was already done previously. Different from get_change_history which only shows changes done via Google Ads UI/API.
Parameters
date_range string Default: last_30_days.
tool_name string Optional filter — exact tool name (e.g. update_campaign_budget).
campaign_id string Optional filter — only changes that touched this campaign.
include_dry_run boolean Default: true. Set false to exclude previewed-only operations.
get_notes Read
Returns persistent notes attached to campaigns OR ad groups. Each note has a `level` field ("campaign" or "ad_group"). When recovering context for an ad group, ALWAYS pull both campaign-level (ad_group_id NULL) and ad-group-level notes — campaign context applies to all its ad groups.
Parameters
campaign_id string Optional — only notes for this campaign.
ad_group_id string Optional — only notes for this specific ad group.
scope string Default "all". Use "campaign_only" to get notes attached at campaign level (ad_group_id NULL), "ad_group_only" for notes attached to any ad group of the campaign.
tags array Optional — only notes matching at least one of these tags.
add_note Read
Persists a free-text note. Attach at the MOST SPECIFIC level applicable: if the change/observation is about ONE ad group (bid, keywords inside, ads, RSA themes), pass ad_group_id. If it spans the whole campaign (budget, geo, bidding strategy, multi-AG insight), omit ad_group_id and only pass campaign_id. Use this to record WHY a change was made, hypotheses, or what to re-check later.
Parameters
campaign_id * string
ad_group_id string OPTIONAL but RECOMMENDED when the note is specific to one ad group. Omit only for campaign-wide notes.
note * string The note content. Be specific: include numbers, dates, hypotheses, re-check date.
tags array Optional tags to organize notes (e.g. [\"experiment\", \"bid-test\", \"to-review\"]).

🔧 Power tools (2)

generate_keyword_ideas Read
Keyword research via Google Keyword Planner (KeywordPlanIdeaService). Returns per idea: text, avg_monthly_searches, competition (LOW/MEDIUM/HIGH), low/high top-of-page bid in micros. ⚠ ACCESS LEVEL : this method requires Basic or Standard Google Ads API access — accounts with a Test/Explorer developer token will get "method is not allowed for use with explorer access". The token level is set on the MCC (https://ads.google.com → Tools → API Center → Apply for Basic Access, ~24-48h approval). language_id default 1002 (FR), 1000 (EN). geo_target_ids: country criterion IDs (2250=FR, 2840=US, 2056=BE).
Parameters
keywords * array
language_id string
geo_target_ids array
execute_gaql Read
Run an arbitrary GAQL SELECT query.
Parameters
query * string

Conventions générales

  • Tools READ : aucun risque, lecture temps réel via Google Ads API / GSC API / Meta Marketing API
  • Tools WRITE : par défaut dry_run=true → renvoie un aperçu JSON sans rien modifier. Vous devez explicitement passer dry_run=false pour exécuter (et vous pouvez désactiver les writes globalement par compte dans gadspilot)
  • Tools mémoire : write léger sur la DB gadspilot uniquement (notes/journal de modifs) — n'appelle pas les API Google/Meta, pas de dry-run nécessaire
  • Toutes les valeurs monétaires sont en micros sur Google Ads (1 € = 1 000 000 micros). gadspilot convertit automatiquement les réponses
  • Tous les writes sont loggués dans /logs avec params + résultat + flag dry-run
Besoin d'aide ? Demandez à Léa 💬
gadspilot assistant
Léa
Assistante IA · gadspilot
Besoin d'un humain ? Contacter le support