Google Ads API v23.1 + April 2026 Core Update Playbook

v23 and v23.1 Release Timeline

Google transitioned from a quarterly to a monthly API release cadence starting with v23 on January 28, 2026. That is the most important operational change of the year — CI pipelines that pinned versions once a quarter will now drift within four weeks and miss metrics that customers expect on dashboards.

Pin the API version explicitly

The biggest practical consequence of the monthly cadence is silent drift. The Python client defaults to the library's current API version, which now changes every 4 weeks. Any script that omits the version= kwarg will start hitting a new API version the first time you pip install -U google-ads — new metrics, new enums, occasionally new breaking changes. Pin explicitly:

# Before — uses whatever the library's default version is today
client = GoogleAdsClient.load_from_storage(path=credentials_path)

# After — explicit pin; intentional bumps only
client = GoogleAdsClient.load_from_storage(
    path=credentials_path,
    version="v23",
)

# Bonus diagnostic: log the actual versions at startup
import google.ads.googleads as googleads_lib
print(f"[env] google-ads {googleads_lib.__version__}, API {client.version}")

With this pin in place, a quarterly schema-drift audit (grep forCallAd, CallAdInfo, other removed resources; compare against the month's release notes) catches deprecations one release ahead of any production break.

Every New Field in v23 and v23.1

Most agency stacks touch only a thin slice of the Ads API surface, which is exactly how features like the new frequency metrics get missed. Below is the exhaustive list of v23 and v23.1 additions ranked by the order you should wire them into production.

v23.1 — the highest-leverage additions

v23 — January carryovers still missed by many stacks

• AudienceInsightsService.GenerateAudienceDefinition — accepts a natural-language description (e.g. “eco-conscious urban parents looking for sustainable wooden toys”) and returns a structured audience definition. Currently allowlist-gated; request access for high-spend accounts before Q3.
• CallAd and CallAdInfo removed — the call-only ad format was officially retired. If your account still references either type, mutations will fail in v23+.
• Two new incentive error codes — MAX_INCENTIVES_REDEEMED and ACCOUNT_TOO_OLD start returning for requests on or after March 11, 2026. Wrap incentive mutations in explicit retry logic now.
• Ad-level scheduling arrived in v23.2, not v23. AdGroupAd.start_date_time and AdGroupAd.end_date_time shipped March 25, 2026 and are limited to specific ad group types. Confirm your ad group type is supported before replacing any cron-based pause/resume script.

Google Ads MCP Server Setup

Google's official Google Ads MCP server is an open-source Model Context Protocol implementation published atgoogleads/google-ads-mcp. It is strictly read-only — it cannot pause campaigns, modify bids, or create assets. That scoping is deliberate: Google elected to keep mutations inside the authenticated REST/gRPC API while letting LLM agents handle the read-heavy reporting use cases that dominate day-to-day account work.

Installation (Claude and Gemini)

Install via pipx and inject three environment variables. Add the resulting command to mcpServers in your Claude or Gemini configuration.

// claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/)
{
  "mcpServers": {
    "google-ads": {
      "command": "pipx",
      "args": [
        "run",
        "--spec",
        "git+https://github.com/googleads/google-ads-mcp.git",
        "google-ads-mcp"
      ],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/abs/path/to/credentials.json",
        "GOOGLE_PROJECT_ID": "your-gcp-project-id",
        "GOOGLE_ADS_DEVELOPER_TOKEN": "22-char-token"
      }
    }
  }
}

For Gemini CLI, add the same block under your Gemini configuration and run /mcp inside the CLI to confirm the server registered. The first invocation triggers the OAuth 2.0 consent flow; service-account credentials are accepted for agency manager-account setups.

Tools exposed

Example GAQL via MCP

Pair the search tool with the new v23.1 frequency metrics to detect audience saturation. This GAQL runs inside the MCP agent and returns rows the agent can summarize as plain English:

SELECT
  campaign.id,
  campaign.name,
  metrics.cost_micros,
  metrics.conversions,
  metrics.unique_users,
  metrics.unique_users_two_plus,
  metrics.unique_users_five_plus,
  metrics.unique_users_ten_plus
FROM campaign
WHERE campaign.status = 'ENABLED'
  AND segments.date DURING LAST_7_DAYS
  AND campaign.advertising_channel_type = 'PERFORMANCE_MAX'
ORDER BY metrics.cost_micros DESC
LIMIT 50

April 2026 Core Update: Information Gain

Google confirmed the completion of the March 2026 core update on April 8, 2026 at 6:12 AM PDT — 12 days and 4 hours after it began on March 27. The update re-weighted a signal the SEO community has been calling Information Gain since a Google patent of the same name surfaced in 2020. In 2026, it moved from one of many signals to the dominant content-quality evaluator.

What Information Gain measures

Information Gain measures how much genuinely new information a page contributes relative to content already ranking for the same query. Two pages can be equally thorough, equally well-structured, and equally fast — but the page that introduces a proprietary dataset, a first-hand benchmark, or an original framework will outrank the page that paraphrases the existing top-10.

A working Information Gain rubric

Score each page 0–2 on the five sub-dimensions below. A combined score of 7+ is the bar for content that meaningfully supports programmatic PPC post-April 2026:

• Proprietary data (0–2): original numbers readers cannot find elsewhere.
• First-hand evidence (0–2): screenshots, transcripts, your own tooling output.
• Original framework (0–2): a named approach or structure you introduced.
• Expert attribution (0–2): named author with verifiable experience on the topic.
• Freshness hook (0–1): tied to a dated event (release, deadline, data cut).

Merchant API in Ads Scripts (Apr 22 Deadline)

The Merchant API arrives in Google Ads Scripts on April 22, 2026 as an Advanced API. The existing Content API for Shopping keeps running until its confirmed August 18, 2026 sunset. Four months is enough runway — but only if you treat April 22 as the start gun, not the finish line.

90-day shipping script playbook

Text Guidelines: Programmatic AI Max Control

Before v23.1, brand-safety teams had to open the Google Ads UI to constrain AI-generated copy. With v23.1, the Campaign.text_guidelinesfield makes brand voice, banned terms, and regulatory guardrails part of the same mutation pipeline as bids and budgets. That alone moves Performance Max and AI Max from “creative wildcard” to “governed channel.”

term_exclusions vs. messaging_restrictions

Mutation example

// Python client — set text_guidelines on an existing Performance Max campaign
from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage(version="v23")
campaign_service = client.get_service("CampaignService")

operation = client.get_type("CampaignOperation")
campaign = operation.update
campaign.resource_name = campaign_service.campaign_path(CUSTOMER_ID, CAMPAIGN_ID)

# Block price-based claims and competitor references
campaign.text_guidelines.term_exclusions.extend([
    "cheapest", "lowest price", "beat any price",
    "[Competitor Brand A]", "[Competitor Brand B]",
])

# Natural-language tone rules (semantic, not literal)
campaign.text_guidelines.messaging_restrictions.extend([
    "Don't generate assets with prices",
    "Avoid superlatives unless substantiated by a cited study",
    "Never imply medical outcomes",
])

client.get_type("FieldMask").from_any_pb(campaign).CopyFrom(
    client.helpers.field_mask(None, campaign._pb)
)

response = campaign_service.mutate_campaigns(
    customer_id=CUSTOMER_ID,
    operations=[operation],
)
print(f"Updated campaign: {response.results[0].resource_name}")

Autonomous Campaign Management Workflows

With v23.1 in production and the MCP server wired up, the shape of an autonomous Google Ads workflow in 2026 looks like this:

1. Observe — the MCP server streams spend, impressions, frequency (unique_users_X), and conversions into an LLM context.
2. Diagnose — the agent flags anomalies (e.g. unique_users_ten_plus / unique_users > 30% suggests frequency saturation).
3. Propose — the agent drafts a mutation (e.g. reduce budget 20%, add messaging restriction, add negative keyword) and writes a change ticket to your queue.
4. Approve— human-in-the-loop signs off if spend delta > 20% of daily budget; below that, policy auto-approves.
5. Execute — REST mutation against the Google Ads API using service-account credentials. MCP is never the write path.
6. Verify — post-change, the agent re-pulls the campaign and confirms the mutation landed before closing the ticket.

Policy gates that keep automation safe

Landing Page Alignment With the Core Update

Programmatic Google Ads management affects the ad layer. Information Gain is scored on what the user lands on. The agencies compounding paid spend into organic share in Q2 2026 are the ones who stopped treating landing pages as disposable conversion assets and started treating them as topical authority anchors.

The paid-to-organic bridge

• Every ad group links to a content hub. The hub includes original benchmarks, a named framework, or a first-hand case study that meets the 7+ rubric score from Section 4.
• Landing page URL matches the content hub.Paid traffic, organic traffic, and direct traffic all reinforce the same URL's engagement signals — exactly what Information Gain weighting rewards.
• Ad copy previews the novel data.Example: “27% conversion lift on price-heavy queries — see the benchmark” instead of “AI-powered ads for your business.”
• Internal link chain is short. Hub → pillar → service page, with no more than two hops. Attention to dwell-time propagation is part of the Information Gain story.

Measurement Guardrails for Programmatic Spend

The metrics that mattered in 2023 (CTR, basic impression share) are insufficient for autonomous workflows. Below is the minimum monitoring surface we run on every managed account in April 2026.

The 90-Day Migration Roadmap

Running every change in parallel is the fastest way to break production. This sequenced 90-day plan is what we ship against inside agency engagements.

Conclusion

Google Ads API v23.1, the read-only MCP server, and the April 2026 core update add up to one coherent message: programmatic PPC management is finally a first-class citizen, but only if you wire the content layer to it. The agencies still running quarterly v22 upgrades, ignoring text_guidelines, and buying generic AI-written landing pages are about to underperform — and the data after April 8 is already confirming it.

Use the 90-day roadmap above. Start with v23.1 client upgrades, layer in MCP reporting, then bring the landing pages up to the Information Gain rubric. The compounding work is on the bridge between paid and organic — that is where the gap between “automated” and “accountable” actually closes in 2026.

Frequently Asked Questions