Google Ads API

Unified Marketing Health payload (Google + Meta) for business owners

Render Marketing Health Report HTML

Agency-ready HTML summary for print or PDF pipeline (Phase 6).

Export Marketing Health report as PDF (Playwright queue)

Idempotent when a cached URL exists on project meta unless force=true.

Get Configured Google Ads Account Info

Account billing and spend exposure (read-only)

Currency, billing setups, account budgets (spending limit, served, remaining) and the summed daily budget of every enabled campaign. Card details, balance and invoices are not available in the Google Ads API.

Fetch Campaigns From Google Ads

Fetch Ad Groups From Google Ads

Fetch Keywords With 30-Day Performance

Fetch Campaign-Level Negative Keywords

Fetch Responsive Search Ads With Headlines And Descriptions

Fetch Per-Headline Asset Performance Ratings (Best / Good / Low / Learning / Pending)

Fetch User Lists (Remarketing And Customer Match)

Fetch 30-Day Performance Metrics Per Campaign

Fetch Configured Conversion Actions

Tracking Templates And Final URL Suffixes (read only)

The account's and every campaign's tracking template and final URL suffix, auto-tagging, and per row the ValueTrack params Google does not fill (unfilled_params), plus the suffix WEMASY recommends.

Fetch Search Terms (Actual User Queries) From Last 30 Days

Fetch Per-Campaign Per-Day Metrics For Trend Detection

Fetch Geographic + Device Performance Breakdown

Fetch Display Placement Performance

One row per website / app / YouTube channel where Display (or PMax/Discovery/Video) ads served, with 30-day impressions / clicks / cost / conversions / view-through. Drives negative-placement exclusions.

Fetch Per-AdGroup Per-Topic Performance (Display topic targeting)

Fetch per-campaign conversion goal config

Returns one row per campaign with the (category × origin × biddable) tuples bound to it. Use `has_overrides=true` to see which campaigns override the account-default conversion goals.

Look up Google Ads language_constant IDs by ISO code

Fuzzy or exact lookup of Google Ads geo_target_constant IDs

Look up in-market and affinity segments by name (read-only)

Google names segments in English. Use the ids as `ad_groups.*.audience.user_interest_ids` on launch-demand-gen-campaign.

Keyword Planner volume for keyword seeds in one geo + language combo

Fetch Google's Own Optimization Recommendations

Fetch Per-URL Performance From Last 30 Days

Fetch Hour-Of-Day x Day-Of-Week Performance Per Campaign

Fetch Audience-Segment Performance Per Ad Group

Fetch Account Edit History From Last 30 Days

Fetch Shared Negative Keyword Lists With Members And Campaign Attachments

Fetch PMax Asset Groups With Performance Metrics

Fetch PMax Asset Performance

Impressions, clicks, cost and conversions per Performance Max line and visual over the last `days` (default 7, max 90), with Google's status and source (ours or Google-made). Read only.

Fetch Metrics Per Ad

Impressions, clicks, cost and conversions per ad over the last `days` (default 7, max 90); optional `channel` (demand_gen, search, display) and `campaign_id`. Read only.

PMax channel breakdown — where Performance Max ads served (Search, Display, YouTube, Gmail, Discover)

Fetch Performance Max Placements

Websites, apps and YouTube placements where PMax ads showed in the last `days` (default 7, max 90), optionally for one `campaign_id`. Impressions only: Google gives no clicks or cost per PMax placement. `suspect` marks apps and games.

Fetch Performance Max Search Terms

Search term categories of one PMax campaign over the last `days` (default 30, max 90): impressions, clicks, conversions and CTR per category label, best first. Feeds the Search campaign next to the PMax (pmax-to-search). Read only.

Fetch Demand Gen Targeting

Per Demand Gen ad group: optimized targeting on/off and its criteria (audience, location, language). Optionally for one campaign_id.

Fetch Asset Automation Settings

Per campaign its asset automation settings (auto videos, image enhancement, landing-page assets, ...), plus the ads Google added itself and the PMax asset links it created.

Fetch PMax Asset Group Audience Signals

Fetch Actual Visited Landing Page URLs After Template Expansion

Map Click gad_campaignid To Campaign

For Performance Max, Google's gad_campaignid click parameter is not the campaign id. Returns {gad_campaignid: {campaign_id, campaign_name}} read from the expanded landing URLs of the last `date_range` (default 90 days).

Fetch Per-Campaign Per-Device Performance Breakdown

Snapshot Current Quality Scores Per Keyword Into History Table

Append-only insert into google_ads_keyword_quality_history. Run on every sync to build a time-series Google's API doesn't expose. AI can compare snapshots across weeks to detect QS drops (landing-page relevance, ad fatigue).

Sync Per-Ad-Group Metrics (Search / Display)

Returns 30-day spend, conversions, clicks, etc. per Search/Display ad group. Used together with AssetGroup metrics (PMax) to render a unified "what's running" panel on the dashboard.

Read campaign geo + language targeting from live Google Ads data

Get Computed Dashboard Insights From Latest Sync

Returns all dashboard panels in one payload: account health, campaign performance, waste/winner keywords, search terms, negative-word candidates, device + geo splits, PMax asset groups, top + broken landing pages, recent change events, daily trend, Google recommendations. Reads from the date-stamped JSON dumps in wemasy-marketing-state, so all insights match exactly what AI would compute from those files.

List Available Sync Snapshot Dates

Returns all date-stamped result folders for time-travel selection in the dashboard. Each date is a full account snapshot taken on that day's sync.

List Launch Template Presets

Returns SMB wizard presets for Google Search and Meta campaigns. Templates live in wemasy-marketing-state/templates/launch/ (source of truth).

Measurement Readiness Check

Green / yellow / red checks for SMB wizards before launch. Reads project domain, analytics flag, and ads connection rows only.

Add Campaign-Level Negative Keyword

Adds a single negative keyword to one campaign via Google Ads MutateCampaignCriteria. Requires explicit confirm flag. Use dry_run to preview the operation without pushing.

Set The Tracking Template / Final URL Suffix (account or campaign)

Refuses ValueTrack params Google does not fill. The previous values are kept in the audit log. "" clears a field.

Make A Conversion Action Primary Or Secondary, Or Set How It Counts

Primary actions are bid on; secondary ones are only observed. counting_type one_per_click counts one conversion per ad click (signups), many_per_click every one (purchases). Give either field or both; the previous values are kept in the audit log.

Widen Or Narrow A Demand Gen Ad Group

Turn optimized targeting on or off and/or remove the ad group's audience criterion. Location and language are never touched. The previous targeting is kept in the audit log.

Turn Google's Auto-Generated Creatives Off

Every asset automation type OPTED_OUT per campaign (one campaign_id or all), types a campaign does not take are skipped with the reason. With remove_auto_created the ads Google added itself are paused and the PMax asset links it created are removed. Before/after in the audit log.

Set The Call To Action Of A PMax Asset Group

Replaces Google's automated call to action with a fixed one (SIGN_UP, START_NOW, LEARN_MORE, ...). The previous one is kept in the audit log.

Set The Final URL Of A PMax Asset Group

The landing page of a Performance Max asset group (apply/final-url only changes ads). The previous URLs are kept in the audit log.

Enable Or Pause A PMax Asset Group

Switches one Performance Max asset group on or off. The campaign status is not touched. The previous status is kept in the audit log.

Exclude Websites And Apps For The Whole Account

Account-level placement exclusions, the only kind Performance Max honours. Websites by domain, apps by Google app id (2-<package> Play, 1-<id> App Store). Already excluded ones are skipped; YouTube, Google and WEMASY domains are refused.

Add Positive Keywords to Ad Group (Bulk)

Adds one or more positive keywords to a single ad group via Google Ads MutateAdGroupCriteria with partial_failure=true. Single batched API call. Requires explicit confirm flag. Use dry_run to preview the operation without pushing.

Remove Keywords (Bulk)

Removes one or more ad-group criteria by resource_name in a single batched mutate with partial_failure=true. Requires confirm=true or dry_run=true.

Add language targeting to an existing campaign

Bulk-add one or more language criteria to a campaign (e.g. layering English on top of a locale language per rule §10).

Find CampaignBudgets with reference_count = 0 (orphaned)

Read-only. Pair output with /apply/remove-campaign-budget to clean them up.

Watch bidding strategy and recommend flips to maximize_conversions

Walks all SEARCH campaigns. For target_spend (Maximize Clicks) campaigns, checks if the 30-day metrics have crossed the data threshold (rule §11). Returns recommendations. Pass apply=true to flip eligible campaigns. Safe to call as a daily cron.

Pause / Enable / Remove A Single Keyword

Used by dashboard "Pause" buttons next to waste keywords. Requires explicit confirm.

Set The Locations Of One Ad Group (Demand Gen)

Demand Gen keeps locations on the ad group. The ad group's positive locations become exactly location_ids (missing ones added, others removed). A dry run shows before / add / remove. Same safety model as the other apply endpoints (confirm OR dry_run required).

Enable / Pause / Remove A Search-or-Display Ad Group

Used by the ad-group detail page's enable/disable toggle. Same safety model as the other apply endpoints (confirm OR dry_run required). Search/Display only — PMax asset_groups need a separate mutation path.

Enable / pause / remove an individual ad (AdGroupAd)

Opt one ad in or out of Google's ad-level asset automation

Demand Gen: opt the image ad out of generate_videos_from_other_assets so Google stops making (and re-enabling) its own video ads from that ad's images. Default type is generate_videos_from_other_assets. Read back in sync/ads (asset_automation).

Remove (delete) an ad from an ad group

Uses AdGroupAdOperation::setRemove() — the only valid Google Ads delete path for ads (status=REMOVED on update is rejected). Destructive; use dry_run first.

Set Device-Level Bid Modifier On A Campaign

Common use: tablet bid_modifier=0.1 (-90%) to effectively kill tablet traffic that doesn't convert. Use 1.0 to reset (no modifier).

Add Ad-Schedule Entries To A Campaign

Adds one or more time-window entries with optional bid modifiers. Common use: kill dead hours (21-23h Mon-Sun, bid_modifier=0.1 for -90%).

Change The Final URL(s) On An Ad

One-step landing-page flip. The most common day-to-day use is routing a campaign to a higher-converting page (e.g. away from /start-with-wemasy back to /start-a-website) without opening the Google Ads UI. Single Ad per call. For bulk operations, call repeatedly with the relevant ad_ids — keeps the audit log surgical and rollback granular.

Update Headlines And Descriptions On An Existing RSA

Mutates the Ad resource's responsive_search_ad assets in place. Requires confirm=true or dry_run=true. Previous assets are captured for rollback.

Swap €1 / limited-offer text on a PMax asset group

Removes linked discount copy and attaches free-start / AI replacements. Requires confirm=true or dry_run=true.

Add Or Remove Campaign Location Targeting (Country / Region / Radius)

Three modes via the `location_id` vs `proximity` keys in the payload: - Country/region: pass `location_id` (Google geo criterion ID, e.g. 2528 for Netherlands). Look up via https://developers.google.com/google-ads/api/data/geotargets - Lat/lng radius: pass `proximity.latitude`, `proximity.longitude`, `proximity.radius`, `proximity.radius_units` (km|miles) - Address radius: pass `proximity.address.{country_code, city_name, postal_code, street_address}` + `proximity.radius` + units Set `negative: true` to exclude rather than include. Set `operation: 'remove'` with `criterion_resource_name` to delete an existing target.

Rename A Campaign

Use for label hygiene (e.g. prefixing paused campaigns with `[graveyard]` or `[reserved]` so the account stays scannable). Names are mutable at any time without affecting ad serving. Reversible via /v1/apply/rollback — the audit log captures `previous_name` for the rollback path.

Upload Image Asset

Uploads a GIF/PNG/JPEG to the Google Ads asset library. File path is resolved against config('google-ads.state_repo_path'). Dimensions must match a standard Google Display size. File must be <= 5MB.

Upload Image Assets (batch, Demand Gen and PMax ratios)

Up to 20 images per call, each as base64 or a public https URL, each with a role: landscape (1.91:1, min 600x314), square (1:1, min 300x300), portrait (4:5, min 480x600), tall_portrait (9:16, min 600x1067) or logo (1:1, min 128x128). GIF, JPEG or PNG, 5 MB at most. Every image is checked before anything is sent. Returns the asset resource names for launch-demand-gen-campaign. Needs confirm=true or dry_run=true.

Create Display Ad Group (enabled, with topic targeting)

Create Image Ad (paused, references uploaded image asset)

Refresh creatives on an existing Display campaign (no recreation)

Keeps campaign + budget + bidding + targeting + ad groups + audit history intact. Uploads new image assets, removes old ads in matching ad groups, creates new ads pointing to new assets. Matched by name pattern: ad_groups = ag-{slug}, existing ads = ad-{slug}-{size} (plus refresh-suffix variants). Always dry_run=true first to preview which ads will be removed, then confirm=true.

Launch Competition Ad Group (into existing competition campaign)

Creates a search ad group under an existing campaign, adds keywords, and optionally creates a paused RSA. dry_run=true validates first.

Add search themes to a PMax asset group (asset group signals)

Add creative assets (headlines, descriptions, long headlines, images) to an existing PMax asset group

Set campaign-level conversion goals (v25 modern path)

Two modes: 1. Explicit: pass `goals` as an array of {category, origin, biddable}. 2. Mirror: pass `source_campaign_id`, the service reads that campaign's biddable goals and applies them verbatim to the target. Always dry_run=true first to preview the resource updates, then confirm=true.

Replace a campaign's language targeting in place

Replace a campaign's geo targeting in place (locations + proximity radii)

Roll Back A Previously-Applied Operation

Reverses the mutation from the given audit log entry (e.g. unpauses a keyword that was paused, removes a negative keyword that was added). Same confirm/dry-run gate as the apply controllers. The rollback itself is logged as a new audit row.

Enable / Pause / Remove A Campaign

Used by the campaign-detail page's "Enable / Disable" toggle. Pause and enable are the reversible day-to-day actions; removed is destructive and cannot be rolled back through this tool.

Budget changes are not done from WEMASY

Nick, 25 Oct 2026: budgets are set in Google Ads itself. The old update-campaign-budget and remove-campaign-budget routes answer 410 with the link to the campaign's budget in Google Ads. Nothing is sent to Google.

Budget changes are not done from WEMASY

Nick, 25 Oct 2026: budgets are set in Google Ads itself. The old update-campaign-budget and remove-campaign-budget routes answer 410 with the link to the campaign's budget in Google Ads. Nothing is sent to Google.

Create Search Campaign (paused, €1/day)

Creates a campaign skeleton: budget + campaign + ad group + geo/language targeting. Budget is locked to €1/day (AI-creation cap). Campaign is created PAUSED. Returns IDs for the new campaign + ad group so callers can chain add-keyword.

Update Campaign (bidding strategy and/or network settings)

Narrow update endpoint — only changes bidding strategy and/or Search Partners toggle. Budget changes are forbidden (rule §1). Status changes use /apply/campaign-status.

Create Display Campaign (paused, €1/day)

Same hard rules as the Search equivalent: budget locked €1/day, status PAUSED, bidding maximize_conversions, network = content network only.

Launch Display Campaign (end-to-end orchestrator)

Single endpoint to take a creative spec, glob banners from disk, chain the 4 Display apply endpoints (upload-image-asset → create-display-campaign → create-display-ad-group → create-image-ad). Returns the full plan + audit_log_ids for every step. Always use dry_run=true first to validate file existence + dimensions, THEN confirm=true.

Launch Search Campaign (end-to-end orchestrator)

Single endpoint to create a paused €1/day search campaign skeleton, add keywords to the new ad group, and optionally create a paused RSA. Returns the full plan + audit_log_ids for every step. Always use dry_run=true first to validate the spec, THEN confirm=true.

Launch Performance Max Campaign (MVP shell)

Creates a paused €1/day PMax campaign with NL geo + Dutch/English languages. When final_url is provided, also creates an enabled asset group with text assets and optional landscape/square marketing images (MARKETING_IMAGE, SQUARE_MARKETING_IMAGE).

Launch Demand Gen Campaign (paused)

Creates budget, a PAUSED Demand Gen campaign and one ad group per entry in `ad_groups`, each with location and language (default Netherlands 2528 and Dutch 1010), an optional audience (custom segment from search terms or URLs plus Google in-market or affinity segments), channel controls, a multi-asset image ad and, when `youtube_video_ids` is set, a video ad. Images and logos are asset resource names from upload-image-assets. Behind the budget mutation gate. The budget is never set from WEMASY (Nick, 25 Oct 2026): the campaign starts PAUSED at EUR 1 a day and the answer carries budget_url, where the owner sets the real budget in Google Ads; a sent daily_budget_eur is ignored. dry_run=true returns the exact operations.

Add Ad Groups To A Demand Gen Campaign

One campaign, one budget, one ad group per product (Nick, 26 Oct 2026). Each ad group gets its own ads and optionally its own audience; with optimized_targeting the audience is a signal, not a hard limit. No budget or campaign setting is created or changed.

Add An Ad To A Demand Gen Ad Group

A new image ad (and video ad with YouTube ids) in an existing Demand Gen ad group, to refresh creatives. Pause the old ad with ad-group-ad-status. Targeting, budget and campaign are not changed.

Set a campaign's daily budget from a merged pull request

Nick, 29 Oct: budgets ship as a PR and his merge makes them live. Give the merged PR's URL and the budget Google has now (expected_daily_eur); a different current budget or a shared budget is refused. Behind the budget gate and the project's daily cap.

List Apply Audit Log Entries

Returns the apply_audit_log rows for the current project, newest first. Each row tells the SPA whether the entry is rollback-eligible (computed by inspecting both the operation type and any prior rollback rows that reference this id).

Run Google Ads Full Sync

Fetches all Google Ads resources for the configured account and writes per-resource JSON dumps into the wemasy-marketing-state repo under countries/{locale}/results/{date}/.

GET-style helper for the SPA to fetch the resource list in render order, so it doesn't have to hardcode the list (and stay in sync as new resources are added)

Generate Declarative State Files From The Latest Sync Dump

Materializes structural/ + creative/ YAML for every enabled campaign in the marketing-state repo. Idempotent — re-running overwrites prior YAML. Curated fields (notes, audiences, last_decision, landing_page_hooks) are preserved across regenerates. PMax campaigns are skipped per marketing-state rule §8.

List Keyword Watchlist Entries

Returns the watchlist (parked + watching keywords) for the current project, newest first. Purely local data — does NOT touch Google Ads.

Park / Watch a Keyword

Adds a keyword to the local watchlist. Idempotent on (project_id, keyword_text, match_type, campaign_id) — calling this twice with the same key updates the existing entry rather than failing. Does NOT pause or modify the keyword in Google Ads. Use /v1/apply/keyword-status separately if you want to pause it too.

Update Watchlist Entry

Update the mutable fields on a watchlist entry: note, status, reactivate_when, campaign_name, ad_group_id, ad_group_name. Identity fields (keyword_text, match_type, campaign_id) are immutable — delete + re-create to change those.

Delete Watchlist Entry

Removes the keyword from the local watchlist. Does NOT touch Google Ads.

List Theses (decision / watcher register)

Returns every thesis recorded for the current project. Filter by ?status=active to get only the watchers the AI should consider on this analysis pass.

Create a Thesis

Records a decision / hypothesis with optional watcher condition + structured context. Examples: "Foreign-language negatives — remove when FR campaign exists", "Broad keyword X has 30d strong perf, ignore 7d dips".

Update a Thesis

Edit any field, including status. Setting status to resolved/invalidated stamps resolved_at automatically. Setting it back to active clears it.

Delete a Thesis

Hard delete. For historical preservation prefer setting status=invalidated instead.