How to use the Google Search Console API

What do you need before the first query?

A service account with the Search Console API enabled and the robot added under Settings → Users and permissions as Restricted — the service account guide covers every console screen. Then the detail that produces the most confusing failure in the whole API: the siteUrl has two forms, and they are different properties.

Request the form you don't have and the answer is 403, not 404 — indistinguishable from having no access. So don't guess: call the sites list first, and configure from what the API says the account can see. Google explains the property types in Add a website property.

What does a searchAnalytics.query request look like?

POST https://www.googleapis.com/webmasters/v3/sites/
     sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer <token>

{
  "startDate": "2026-07-01",
  "endDate": "2026-07-28",
  "dimensions": ["query"],
  "rowLimit": 25000,
  "startRow": 0
}

Rows come back with keys (dimension values in order), clicks, impressions, ctr, and position. Dimensions can combine query, page, date, country, device, and searchAppearance — full request shape in the searchAnalytics.query reference. Worth knowing: this is one plain POST with a body you fully control. The system behind this post calls it with fetch directly — pulling in the entire generated googleapis package for one endpoint buys hundreds of megabytes of dependency for no correctness.

How do pagination and retries actually work?

1. Ask for the maximum: rowLimit: 25000 — Google's hard cap per request (see usage limits).
2. Page by advancing startRow by the rows received; stop when a page comes back short.
3. Retry only 429, 500, and 503, with exponential backoff. Errors like 403 are configuration, not weather — retrying them just hides the message.
4. Put a ceiling on total pages and record truncated: true when you hit it — a report that says it might be incomplete is honest; one that silently is, lies.

const RETRY_DELAYS_MS = [1000, 2000, 4000, 8000, 16000]
// retry only 429 / 500 / 503; page with startRow until
// rows.length < rowLimit; cap total pages and mark truncated

Why pull several small shapes instead of one big one?

The intuition is to pull [date, query, page] once and derive everything else. It's wrong, for a documented reason: Search Console withholds rare rows for privacy, and the more dimensions a request has, the more it withholds. Each dimension you add fragments the data into smaller buckets, and small buckets disappear.

The gap between totals and sum of by-query rows is itself a metric: the share of traffic on anonymized queries. Surface it as a first-class caveat instead of discovering it in a spreadsheet argument.

Which limits can't be coded around?

• 16 months of history, then gone. The API is not an archive. If you want year-over-year in two years, pull windows now and store them — the system behind this post commits raw JSON responses to git, 28-day windows frozen once written.
• The last ~3 days are unsettled. Freeze historical windows, and re-pull only the trailing partial window until it clears the settling period.
• Position is impression-weighted. Not a rank. Never present it as one.

What to do with the archive once it exists — turning it into CLI reports an AI agent can consume — is its own build note.

Questions