Google Search Console API: a practical SEO guide

What is the Google Search Console API?

The Google Search Console API lets software request selected reports from properties the authorized Google user can access. It is useful when you have many sites, want repeatable SEO reports or need to analyze data in a script or an AI assistant.

If you only need to inspect one page, the Search Console interface is often faster. The API becomes valuable when the workflow is repetitive: comparing last month’s pages, building a daily dashboard or filtering hundreds of high-impression queries.

Read the official API reference for the current resources and authentication requirements.

Which tasks can you automate?

This distinction matters when evaluating SEO tools. A connector can only expose capabilities provided by its integrations and authorization scope.

Example: ask for Search Analytics rows

A programmatic request uses the Search Analytics endpoint for an authorized property. The following is an illustrative request body with a fixed date range:

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-28",
  "dimensions": ["page", "query"],
  "rowLimit": 1000,
  "startRow": 0,
  "type": "web"
}

Your client sends this with the required OAuth authorization to the Search Analytics query method. Results contain the dimension keys, clicks, impressions, CTR and position.

For a complete report:

1. Confirm the exact property identifier and the Google user’s access.
2. Use complete reporting dates, because recent data can be provisional.
3. Choose dimensions that answer one specific question.
4. Page through results where available using startRow and rowLimit.
5. Preserve raw numbers before an AI assistant summarizes them.

The API allows a row limit up to 25,000 per request, but a request is not a guarantee that all query-level records are available. See the official method documentation for limits.

Example: find high-impression pages with low CTR

Suppose you retrieve page-level results for the last 28 complete days. Sort by impressions, then filter down to pages with enough data to draw conclusions. For each candidate, fetch query-level data and inspect which searches make up its impressions.

An average CTR of 2% is not universally good or bad. A branded query at position one behaves differently from a broad informational query at position nine. Do not rank pages by CTR alone.

See our step-by-step low-CTR workflow.

Example: inspect a URL

The URL Inspection API can report indexed status, canonical information, last crawl indicators and other signals for a specified URL. It is useful for reviewing a shortlist of important pages.

It cannot force indexing and should not be described as a ‘submit URL to Google’ API. Google’s Indexing API is limited to particular JobPosting or livestream BroadcastEvent page types, not general blog posts.

What are the limitations?

Privacy and result coverage. Google omits some anonymized queries, and API results are not a guaranteed full query dump.

Quotas. Requests consume quota, especially expensive date ranges or URL inspections. Review Google’s current usage limits before designing a high-frequency crawler.

16-month history. You cannot fetch older Search Console performance data just by using an API. If you need long-term retention, start an ongoing export.

Different metrics. Search Console clicks will not match GA4 sessions one-for-one. Read why the numbers differ.

How to run a real Search Analytics request

If you are a developer or want to validate a connector, start with Google’s documented REST method. Authenticate with an OAuth 2.0 access token for a Google account that has permission to view the property.

The request below illustrates the shape of a call. Replace the token, the URL-encoded property path and the dates with your own values. Never commit a token to a repository or paste it into an AI conversation.

curl --request POST \
  "https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fexample.com%2F/searchAnalytics/query" \
  --header "Authorization: Bearer YOUR_OAUTH_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "startDate": "2026-09-01",
    "endDate": "2026-09-28",
    "dimensions": ["page"],
    "type": "web",
    "dataState": "final",
    "rowLimit": 1000,
    "startRow": 0
  }'

A domain-level property uses a different site identifier, such as sc-domain:example.com, so its path must be encoded accordingly. It is not interchangeable with https://example.com/.

The response contains a list of rows with dimension keys and measurements. Empty rows do not automatically mean your Google OAuth credentials are wrong; the property or date window may contain no eligible data.

For production usage, validate the HTTP status and error payload separately from an empty result set. Respect rate limits and retry transient failures with bounded backoff.

API reporting mistakes that create false SEO conclusions

Google’s Search Analytics API reference documents the grouping and aggregation options, pagination and final versus fresh data behavior.

Should you use the API directly or an MCP server?

Choose the direct API if you are building a data warehouse, need custom request orchestration or require tight control of authentication, scheduling and logging.

An MCP connector is more convenient when a marketer or founder wants to ask an assistant questions such as “Which landing pages lost clicks?” without maintaining a custom script.

Neither method magically provides information that Google does not expose. The quality of the answer still depends on the requested dimensions, date range, available Google permissions and the assistant’s interpretation.

Search Console API: frequently asked questions

Does the API cost money per SEO query?

Google’s Search Console API is generally available subject to quotas and project requirements rather than a standard per-query price. An MCP provider may separately charge for its service; verify current service terms.

Can I retrieve data from two years ago?

Not through the standard Search Analytics history once the data is outside Google’s retention period. Set up scheduled retention before the older records expire.

Why does my API response have fewer keywords than the UI?

Search Console can omit anonymized queries, and query results are subject to row limits and other restrictions. The official methodology explains why reported totals and detailed tables may not fully match.

Can an MCP server write changes to my site?

MCP is a tool-connection protocol; actual allowed operations depend on the particular server, tool definitions and granted permissions. Search Console reporting tools do not automatically grant permission to edit website code.

Connect the data to your AI assistant

You can build your own OAuth client and API pipeline. An alternative is an authorized MCP connector that exposes selected Google Search Console operations to an assistant, so you can ask analytical questions in plain language.

If you want an MCP workflow rather than maintaining API code yourself, explore GSC Magic. For hands-on setup, see our Claude guide or ChatGPT guide.