The Google Search Console API: Six Endpoints, One That Matters, and the Auth Step Everyone Misses

The Search Console API has a reputation for being fiddly, and it is not. It has six endpoints, one of which does the real work, and a single authentication step that fails silently enough to cost people a whole afternoon.

This covers the surface, the auth, the first two calls, and the two flags that explain almost every "my numbers do not match the interface" question.

What the API is, and what it is not

It is the same Search Console data, read programmatically. That sentence sets both the appeal and the ceiling.

• Same window. A rolling 16 months, with the oldest day dropping off every morning. The API cannot reach further back than the interface can.
• Same privacy line. Anonymised queries have no row over the API either. More rows of the visible long tail is not the same as more queries.
• Twenty-five times the rows. 25,000 per request against the interface's 1,000, paged. This is the actual reason to use it.
• Schedulable. The interface needs a human. A cron job does not, which is what turns a report into a pipeline.

What it is not is a warehouse. It reads; it never stores. Any history beyond the window is something you built.

Every endpoint, in one table

The whole API fits on one screen, which is unusual for a Google product and makes it much less intimidating than the documentation implies.

Note the split hosts. Search analytics, sites and sitemaps live under the Webmasters v3 base; URL inspection is on its own host with its own quota, and is the newest part of the surface.

Authentication: the step that trips people up

Everything is OAuth 2.0. What differs is who consents, and that choice determines how your integration dies later.

Two scopes exist, and you should ask for the smaller one:

• https://www.googleapis.com/auth/webmasters grants read and write. You need it to submit sitemaps or manage properties.
• https://www.googleapis.com/auth/webmasters.readonly grants read only, and is what a reporting integration should request. People read consent screens.

The service account gotcha

This is the afternoon. Creating a service account in Google Cloud and enabling the API grants it exactly nothing in Search Console, and the failure looks like a permissions bug rather than a missing step.

1. Create the service account in your Google Cloud project.
2. Copy its email address, which ends in .iam.gserviceaccount.com.
3. Open Search Console, pick the property, then Settings → Users and permissions.
4. Add that email as a user, exactly as you would add a colleague. Full for write access, restricted for read.
5. Repeat for every property. There is no bulk step.

Until step four, every call returns a 403 that reads like an auth problem, because technically it is one: the credential is valid and has no access to anything. Who can perform step four is covered in users and permissions, and the answer is owners only.

The quickstart: your first two calls

Make sites.list your first request every time. It is cheap, it proves the credential works, and it prints the exact siteUrl strings every other endpoint insists on.

GET https://www.googleapis.com/webmasters/v3/sites

The response names your properties in the exact string format every other endpoint demands. Two shapes:

• sc-domain:example.com for a domain property.
• https://example.com/ for a URL-prefix property, trailing slash included.

Copy them verbatim and URL-encode them wherever they sit in a path. Then the call you came for:

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query

{
  "startDate": "2026-08-01",
  "endDate": "2026-08-28",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0,
  "dataState": "final"
}

That is the whole quickstart. Everything else is choosing dimensions, filtering, and paging.

searchAnalytics.query in detail

One endpoint, and most of the API's value. The body is small and each field changes the shape of what comes back.

• dimensions: any of query, page, country, device, date, searchAppearance. Combine them and each row is a unique combination, which multiplies row counts fast.
• type: which surface you are asking about. Web, image, video, news and discover are separate datasets, not filters on one.
• dimensionFilterGroups: the API equivalent of interface filters, including regex. The free GSC regex generator writes patterns that work in both.
• rowLimit and startRow: paging. Request 25,000, then increment startRow by 25,000 until a response returns fewer rows than you asked for.

There is no total-count field, so the short response is the end-of-results signal. A loop that waits for an empty page instead will make one wasted request every time, which is harmless but tells you the author never read the response shape.

Why your API numbers do not match the interface

This is the most common support question about the API and it is almost never a bug. Two flags explain nearly all of it.

• dataState. It defaults to final, which excludes the most recent days while they are still settling. Set it to all to include fresh, incomplete data, and expect those last days to keep moving.
• aggregationType. Whether totals are counted by property or by page. Adding the page dimension changes the aggregation, and therefore changes the totals, which surprises people who expected filtering to be lossless.
• Anonymised queries. The moment you add the query dimension, hidden queries drop out. Your query rows will always sum to less than your unfiltered totals.

Rule of thumb: compare like with like. Rows to rows, totals to totals, one dataState throughout. A mismatch between an API pull and a screenshot usually means the two used different settings, not that one of them is wrong. The same discipline applies when you cross into GA4, where the gap is structural rather than configurable.

Index status, and the Indexing API misconception

People come looking for an endpoint that gets pages indexed. It exists, it is a different product, and it almost certainly does not apply to you.

• The Indexing API is narrow. Google accepts it only for pages carrying JobPosting or BroadcastEvent structured data. Calling it for ordinary content does nothing, whatever a plugin claims.
• URL Inspection is what you want. urlInspection.index.inspect returns Google's index verdict for a URL, the canonical it chose, the last crawl date and rich-result verdicts.
• Its quota is real. 2,000 calls per day and 600 per minute, per property. That is generous for spot checks and small for a nightly sweep of a large site.

For bulk indexability across a site, inspection is the wrong shape entirely: you want a crawl, and the free page indexability checker covers the common case. What the statuses mean once you have them is in the page indexing report guide.

Sitemaps: the endpoint worth wiring into a deploy

The sitemaps endpoints get overlooked because submitting one by hand takes ten seconds. Doing it automatically is still worth the ten minutes.

• sitemaps.submit takes the property and the full sitemap URL. It is idempotent, so resubmitting on every deploy is safe and cheap.
• sitemaps.list returns status, warnings, errors and counts for everything submitted. The submitted-versus-discovered gap is a finding on its own.
• Alert on the gap, not the submission. A sitemap that submits cleanly and discovers a third of its URLs is the failure worth catching in CI.

Validate the file before you submit it rather than after Google complains: the free sitemap validator checks it against the protocol, and the sitemap checker live-checks the URLs inside it.

Limits, quotas and what the API will not give you

The honest list, so you find out here rather than three days into a build.

• No link data. The Links report has no endpoint. If you want the links report programmatically, you cannot have it.
• No Core Web Vitals. Not exposed. The CrUX API is a separate product with a different dataset.
• No manual actions or security issues. Both are interface and email only, which matters if you hoped to monitor a client roster programmatically.
• No enhancement reports. Structured-data validity is not available through this API.
• Quota you will not hit normally. Per-project and per-user limits are generous for reporting and easy to exhaust with a retry loop that has no backoff. Handle 429 properly from the start.

API, interface or bulk export

Three ways to read the same data, and the choice is about depth against setup rather than about quality.

Most teams that get this right run two of the three: the BigQuery bulk export as the archive, because it is the only route that beats the 16-month window, and the API for the specific questions they ask weekly. The interface stays for the reports the API does not expose at all.

If the goal is a language model reading your Search Console data rather than a dashboard, the API is one layer below where you want to be: the Search Console MCP routes cover what sits on top of it.

Primary sources

• Google for Developers: Search Console API reference
• Google for Developers: searchanalytics.query
• Google for Developers: URL Inspection API
• Google Search Central: Indexing API quickstart, and its eligibility limits