Sign in
Updated 8 November 2026 · Practical guide

Google Search Console API for your coding agent

Use Claude Code, Codex, Cursor, OpenCode or another MCP-compatible coding agent to improve your site's SEO with real Google Search Console evidence. Keep the AI and code editor you already use. Connect your data, find the right page to fix, review the diff, and measure what happens after shipping.

The Google Search Console API returns your site's search performance as structured data: queries, pages, clicks, impressions, click-through rate (CTR), and average position. The useful part for a developer or technical SEO is what happens next: your coding agent can connect those numbers to the pages and templates in your repo and propose a specific, reviewable fix.

Google Search ConsoleRefreshAgent evidence toolsYour coding agentReviewed code change

Two ways to access the Google Search Console API

You can integrate directly with Google's API or use a managed bridge. Both give access to first-party search data; neither automatically knows how to improve your website.

Direct Google API

Register a Google Cloud project, configure OAuth 2.0, request a Search Console scope, store tokens, call the endpoints, and write code to interpret the returned rows.

Best for: building your own integration, custom reporting or data pipelines.

See an authenticated API request.

RefreshAgent + your agent

Connect your Google account once, then let an MCP-compatible coding agent call read-only Search Console tools. Your agent handles reasoning and repository work; RefreshAgent supplies authorized data and deterministic comparisons.

Best for: using Claude Code, Codex, Cursor, OpenCode or another compatible client to work on SEO without building Google OAuth yourself.

Set up the managed connection.

RefreshAgent does not replace your chosen AI model or charge you for its reasoning when you use the MCP data tools. It also does not push site changes simply because you asked an SEO question. Review and explicitly approve changes in your own coding workflow.

Connect Search Console to the coding agent you already use

Use RefreshAgent's remote MCP endpoint: https://refreshagent.com/mcp. The same read-only SEO data can be used from compatible tools; setup differs by client.

01Pick your client and add the MCP server

Claude Code

claude mcp add --transport http --scope user refreshagent https://refreshagent.com/mcp

Inside Claude Code, run /mcp, choose RefreshAgent, and follow the sign-in flow.

Codex CLI

codex mcp add refreshagent --url https://refreshagent.com/mcp
codex mcp login refreshagent

OpenCode (current V2 CLI)

opencode mcp add refreshagent --global --url https://refreshagent.com/mcp
opencode mcp auth refreshagent

Cursor, VS Code and other MCP-compatible coding agents: use your client's remote HTTP MCP setup, add https://refreshagent.com/mcp, and complete OAuth if supported. Don't paste Google access tokens into prompts or project files. For client-specific setup and current commands, use the RefreshAgent MCP installation guide.

02Authorize the site

Sign in to RefreshAgent with a Google account that can view the Search Console property. Choose the exact domain or URL-prefix property your agent should analyze. You don't need to create your own GCP project for the managed path.

03Give the agent a specific task

Start with a narrow diagnostic, not a generic request to "do SEO":

Use RefreshAgent's live Search Console data for my site.
Compare the latest two complete 28-day periods.
Find the pages with the largest ranking or click losses.
For each page, show the dates, clicks, impressions,
CTR, and average position, then inspect the code/content
in this repository. Recommend the smallest safe improvement.
Do not edit files until you show me the evidence and plan.

A practical SEO coding-agent workflow: evidence → diff → verification

Search Console helps decide where to look. Your coding agent can inspect the actual source to decide what might be wrong. The combination is stronger than either a generic SEO checklist or an ungrounded LLM suggestion.

  1. Select an opportunity. Compare equal, finalized periods and list the specific affected URLs. Separate lost impressions, position changes and low CTR; they are not the same diagnosis.
  2. Check search intent. Read queries for the exact page (where available), inspect the live SERP and compare the page's answer with the questions searchers are asking. Account for seasonality and query anonymization.
  3. Inspect the repository. Find the actual route, content source, canonical, meta tags, internal links and rendered HTML. Check whether a shared component or several pages are responsible for the same issue.
  4. Propose a bounded edit. Show the evidence, affected files, proposed wording or code, and likely trade-offs. Avoid fabricated statistics, keyword stuffing, duplicate landing pages and unapproved redirects.
  5. Test and review. Run the project's relevant tests, check generated HTML, accessibility and mobile layout, then open a PR or review the diff before merging.
  6. Verify the deployed page. Confirm the live HTML and indexing signals; then observe comparable Search Console periods after Google has processed the change. A merged PR is not proof of higher rankings.

Useful follow-up prompts: Find near-page-one queries and map them to existing pages; Identify content sections missing for this page's actual queries; Review these two pages for overlapping search intent before recommending a redirect.

For deeper coding workflows, see the open-source SEO agent, the Google Search Console MCP guide, and the Claude-specific walkthrough.

Real example: more impressions, fewer clicks

We tested this workflow on RefreshAgent's own Google Search Console API page rather than inventing a case study. This is a historical Search Console snapshot, not a simulated result or an SEO improvement claim.

1,936Impressions · latest 90 days (+59%)
7Clicks · latest 90 days (previously 11)
16.1Average position (previously 11.6)
Page-filtered Search Console comparison as observed 8 November 2026. Latest period: 9 August–6 November 2026. Previous period: 11 May–8 August 2026.
MetricPrevious 90dLatest 90d
Impressions1,2171,936
Clicks117
CTR0.90%0.36%
Average position11.6416.08

What the agent should conclude: visibility increased, but the page's average position became worse by roughly 4.4 places and click-through rate declined. This is consistent with a ranking-related contribution to lost clicks, not proof that weak page content caused the change.

What we found in the source: the previous page used a generic template with five prompts but no actual API request, worked response or real coding-agent workflow. This guide adds those missing pieces. Any ranking effect must be evaluated later, after deployment and enough finalized Search Console data exists.

Evidence: RefreshAgent Search Console property sc-domain:refreshagent.com, exact page /google-search-console-api, two complete 90-day periods ending 6 November 2026. Query-level Search Console reporting can omit anonymized queries; do not use site-wide query rankings as though they were confirmed for this URL.

Direct Google Search Console API example

If you want to write your own integration, the Search Analytics endpoint is POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query. A property can be a URL-prefix property or sc-domain:example.com. The response contains grouped search-performance rows.

Request: queries for one URL

This is an example request body. Replace the dates and page URL with your own; it is not a RefreshAgent MCP tool call.

{
  "startDate": "2026-10-01",
  "endDate": "2026-10-28",
  "dimensions": ["query", "page"],
  "dimensionFilterGroups": [{
    "filters": [{
      "dimension": "page",
      "operator": "equals",
      "expression": "https://example.com/guides/seo"
    }]
  }],
  "rowLimit": 1000
}

Send it with a valid OAuth 2.0 access token, using the Search Console property's identifier in the URL:

curl -X POST \
  "https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
  -H "Authorization: Bearer $GSC_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"startDate":"2026-10-01","endDate":"2026-10-28","dimensions":["query","page"],"rowLimit":1000}'

The curl command shows the basic query/page aggregation; add the page filter from the JSON example when investigating one URL. GSC_ACCESS_TOKEN must be an actual authorized OAuth token, not an API key. Never commit it to Git or paste it into an AI conversation.

Response: how to interpret the rows

{
  "rows": [{
    "keys": ["example seo query", "https://example.com/guides/seo"],
    "clicks": 12,
    "impressions": 800,
    "ctr": 0.015,
    "position": 9.4
  }]
}

Illustrative JSON only, not observed traffic. CTR is a decimal (0.015 means 1.5%); average position is not a fixed rank for every impression.

Google's official Search Analytics API reference describes filters, aggregation types, response fields and pagination. The Google query tutorial includes programmatic examples.

Authentication, quotas, and the data your agent can trust

Can I use a Google Search Console API key?

Not to read private Search Console performance data. Google's Search Console API uses OAuth 2.0, with scopes such as https://www.googleapis.com/auth/webmasters.readonly. An API key alone does not authorize private query and page metrics. See Google's authorization guide.

Does the API return every search query?

No. Google can withhold anonymized queries, and Search Analytics returns top rows under internal data limitations. Results are not an exhaustive event log. A request accepts up to 25,000 rows, with startRow pagination; pagination does not remove the underlying data-completeness limitations. Be explicit about page versus property aggregation when comparing totals.

Is the newest data final?

Not always. The default dataState is final; requesting all can include incomplete recent data. Compare equal finalized periods for decisions. Search Console measures visibility and clicks in Google Search; GA4 measures subsequent on-site sessions and actions, so their totals do not need to match.

What does RefreshAgent cost?

Interactive, authenticated read-only Search Console requests are available on Free under technical fair-use safeguards and Google's quotas. Your coding agent uses your own AI subscription or model tokens. Paid plans cover optional hosted automation, scheduled work and additional capacity; GA4 and other metered Google-data access have separate allowances. See current plans and limits. Neither a connection nor a free read authorizes paid jobs or website edits.

Common questions from coding-agent users

Will this work with my coding agent, or only Claude?

It is not tied to Claude. RefreshAgent exposes a remote MCP endpoint for clients that support the required transport and sign-in flow. Claude Code, Codex and OpenCode setup commands are shown above. For Cursor and other clients, use their current MCP configuration UI and check OAuth support. See the connection guide.

Will RefreshAgent edit my source code?

Reading Search Console through MCP is a data operation. Any repository edits are a separate workflow in your coding agent or explicitly authorized hosted work. Review the proposed diff, run tests and approve the delivery separately.

Should I create one page for every related Search Console keyword?

No. Map each query to the page that best answers its intent. This page is the broad API and coding-agent workflow guide; the MCP page goes deeper on the protocol and installation, and the Search Console API bridge page addresses a narrower connection use case. Avoid near-duplicate articles.

Can I run this for client sites?

Yes, for properties the connected Google account is authorized to view. Keep clients' data and repositories separated. Read access does not grant permission to publish edits or use paid compute on their behalf.

Put your agent to work on the pages that matter

Connect once, ask for a page-specific Search Console diagnosis, then let your preferred coding agent inspect the repository and prepare a reviewable change. Keep evidence, implementation and later outcomes separate.

Connect your coding agent Explore the MCP setup Compare plans