Search Console API

If you are deciding whether to wire search data into an agent, here is the operator view. GetAgentTools lists only what I actually use, with a verdict and no sponsored placements. Verdict first, then the detail.

Verdict: RUNNING. In one line: real search queries and positions, from the source.

What the Search Console API is

Search Console is the free Google product that shows you how your site performs in Google Search. The API is the same data without the interface: an agent asks for it in a request and gets numbers back, instead of a person clicking through charts and exporting CSVs.

The data is the part that matters, because nothing else has it. Google is the only party that knows every query your pages appeared for, including the ones nobody clicked. Third parties estimate this from panels and crawls. Search Console reports it from the source, for the site you have verified, going back sixteen months.

Access is scoped to ownership. You verify a property once, and the API answers only for properties your account can see. This is a tool for measuring your own site, not for spying on anyone else's.

Why the Search Console API is RUNNING in my stack

Every content decision on this site starts from it: real queries, real positions, and whether Google indexed the page at all. Estimates describe the market; this describes my pages.

Concretely: the blog on this site is planned from this API. An agent pulls the queries Google attributes to the domain, groups them by intent, and the clusters with real impressions and no page answering them become the writing queue. One caveat belongs here rather than in a footnote: Google withholds rare queries for privacy, so the query rows never sum to the property total, and on a young site with a long tail that gap is at its proportionally largest. Even so, on a domain eighteen days old the report was small enough to read whole and still settled the entire first content batch: one topic held over a third of all impressions, every one of them landing on a single page at an average position of 72. No estimate would have told me that, because an estimate describes the market, and this was a fact about my pages.

The second call earns its keep on a different question. URL Inspection told me that a hub page had been discovered by Google and never crawled, weeks after launch. The page was fine. The problem was the site: nothing in the navigation linked to it, so Google had no reason to fetch it. One nav change later the distinction mattered again, because inspection is how you verify the fix took. Fail to separate not indexed from not crawled and you will fix the wrong thing.

The two calls that matter

The API surface is small and most of it is property management. Two methods do the real work.

Search Analytics answers what happened in search: clicks, impressions, click-through rate and average position, sliced by query, page, country, device and date, in one request. The dimensions combine, which is the underrated part. Query plus page together tells you which URL Google chose for which intent, and that combination is where cannibalisation and wrong-page rankings become visible.

URL Inspectionanswers what Google thinks of one URL: indexed or not, last crawl time, the canonical Google picked. It turns "why does this page get no traffic" from a debate into a lookup. The states are precise, and the difference between them decides your next move: a page that is unknown needs any path in at all, a sitemap entry or a single link; a page discovered but not crawled is known and judged not worth fetching, so it needs internal links that say it matters; a page indexed and invisible needs better content.

Google Search Analytics API: what searchanalytics.query returns

searchanalytics.query is the Search Console API method behind the search numbers on this page. One POST per property returns rows of clicks, impressions, CTR and average position, grouped by the dimensions you ask for and filtered by the ones you name, for any date range inside the last sixteen months.

The dimensions are query, page, country, device, date and searchAppearance, plus hour for the hourly view. Filters sit in dimensionFilterGroups and combine with AND; the operators are equals (the default), contains, notContains, notEquals, includingRegex and excludingRegex. rowLimit accepts 1 to 25,000 rows and defaults to 1,000; past that you page with startRow, and a page shorter than the limit means there are no more rows available for that query. Search Console can still omit rows because of internal limits. type picks the surface: web by default, or image, video, news, discover and googleNews. dataState sets freshness: final (the default) returns finalized days only, all adds fresh rows the reference says may still change noticeably, and hourly_all goes with hour.

Two things the rows never say. Aggregation by page counts the canonical URL, so page rows and property totals can differ. And rare queries are anonymized: Google leaves them out of the query rows but keeps them in the chart totals unless a query filter is applied, so a breakdown by query comes in under the property total. My own 28-day read (18 August to 14 September 2026) returned 550 query-page pairs across 548 queries; on a client property I audited in September 2026, the same threshold hid 92.7 percent of clicks from the query table.

Your pages vs market estimates: when each wins

This is not an argument against keyword tools. A crawler-based tool sees the whole market, including the queries your site has never appeared for, and that outside view has a place in the SEO stack I run. But the two sources answer different questions, and mixing them up wastes writing time.

Estimates answer "how big is this topic". Search Console answers "what is my site already being shown for". For a new site the second question is the one that pays, and not because a deep position is nearly a win, it is not. The value is in the concentration: when one topic gathers a third of all impressions onto one page, Google has told you which door it considers yours, and that is a measured opening even when the position itself says the page needs rebuilding. The failure mode of planning from estimates alone is writing for volume you will never see; the failure mode of Search Console alone is never hearing about topics adjacent to yours. Start with your own data, spend estimates on what it cannot see.

One trap in the middle: navigational queries. The biggest query on this domain by impressions is another product's bare name, and you will not outrank a product for its own name when the searcher's intent is to reach that product's site. A review of it is a different query, and worth writing; the bare brand is noise in your report. Position alone does not mark the difference. Read the query, not just the number.

Who the Search Console API is best for

Planning content from measured demand. If content decisions for a site you own are part of any agent workflow, this is the cheapest evidence you will ever wire in. It is also the natural first integration for an SEO agent: read-only, free, and the output maps directly onto a writing queue. Mine reads it through Claude Code on a schedule and the numbers land in the same place the drafts do.

When to skip the Search Console API

The site you care about is not yours.The API only answers for properties you have verified, so competitive research is out of scope by design. If the question is about someone else's site or about a market you have no presence in, this tool has nothing for you and a crawler-based tool is the right call.

I would also skip the API layer, not the product, for a site you look at once a month. The web interface answers occasional questions fine. The API pays when reading the data is a job that repeats, which for an agent is the definition of the job.

How much does the Search Console API cost?

Nothing. There is no paid tier, no billing account requirement, no per-request charge. The real limits are quotas, and they are generous for the single-site case:

• Search Analytics: 1,200 queries per minute, per site and per user
• URL Inspection: 2,000 inspections per day and 600 per minute, per site

Treat the numbers as the shape and check the published limits before building anything chatty. For scale: my daily read of an entire small property is a handful of requests. The quota that actually binds is URL Inspection on large sites, where 2,000 a day meets a sitemap with fifty thousand URLs and loses.

How to set up agent access to Search Console

1. Verify the property in Search Console first, as a human, once. Nothing below works without it.
2. Create a service account in a Google Cloud project. No OAuth consent screens, no browser flows for the agent, just a key file it can use headlessly.
3. Enable the Search Console API in that same project, or every call below answers with a 403 and you will debug the wrong layer.
4. Grant the narrowest scope: webmasters.readonly. Content planning is a read job. The write scope exists and you do not need it.
5. Add the service account's email address as a user on the property, the same way you would add a person.
6. Keep the key file outside the repository and out of the prompt, like any credential. A leaked read-only search key is a small leak, and small leaks are still rotations.
7. Start with one call: last twenty-eight days, dimensions query and page, sorted by impressions. That single table is most of the value, and where the numbers should land is its own decision, mine go to a spreadsheet the whole team can read.

Search Console API FAQ