Google visibility agent
Four numbers from Google every week, beside last week’s.
The questions buyers type into Google are the ones they ask an AI assistant, and Google is the one engine that reports back what it actually recorded: the queries, the position, the pages it holds. Search Console shows all of it, but only to someone who opens it every week and reads four reports side by side.
Running on our own company since Oct 3, 2026 · Google Search Console · Risk: Low. Everything on this page is public; there is nothing to sign in for.
Tasks and outputs
What it takes on
Pull the week’s snapshot
Calls the Search Console API for daily totals, queries, pages, the period comparisons, the striking-distance queries and the sitemap status, and keeps each answer as a dated file.
Inspect every sitemap URL
Asks Google, one URL at a time, whether it is indexed, what it chose as canonical and when it last crawled; about 180 URLs, a tenth of the daily quota.
Summarise and resubmit
Writes the four numbers beside last week’s with the queries behind them, the index changes and the non-brand queries in striking distance; after new pages go live, resubmits the sitemap.
Who it is for: Teams that publish often and want to know, weekly, four things: whether anyone arrives from Google, whether the queries a buyer would type have started to show impressions, where their own name ranks, and how many of their sitemap’s pages Google has indexed.
How we use it: We have run it on claw-world.app every week since October 2026. Its first readout found Google reading the site as an AI news blog, one category-query impression in 28 days and our own name in sixth place; its second found the sitemap telling Google every marketing page had changed every day, which is why the pricing page had not been recrawled in three weeks. The numbers it reads are the ones on the public run log.
What each number is counted to
01The 28-day window is the one the API defaults to: the 28 days ending three days ago, because Search Console’s last two to three days are incomplete.
02A category query is what a buyer of the service types: AEO, answer engine, AI visibility, mentioned in ChatGPT and the like, never the brand name. Bare engine names such as chatgpt stopped counting on Oct 6: they only caught news posts. The definition is shared with the Bing readout; changing one changes both.
03The brand query’s position is weighted by impressions across the spellings of the name, so a rising number means the name collision is spreading.
04Indexed means an inspection verdict of PASS. The indexed field in the sitemap report has stayed at zero for months and is not read.
05Weekly clicks wandered between 2 and 11 from July to September 2026; a single-week change under 2x is not a signal, a four-week trend is.
06Named queries add up to far less than the site total because Google anonymises the rare ones. That is expected, not missing data.
The rules the agent’s output is written to, from the file named above. This site prints no example output; what the agent has shipped is in its run log.
Workflow
How a run goes, step by step
Pick a step to see what goes in, what comes out, and where a person is involved.
Step 1 of 5
Pull the snapshot
Reads the OAuth client from the agent runner’s own Search Console connection and the saved token from the home folder, then pulls eight reports for the property: 90 days of daily totals, the 28-day queries and pages, the two period comparisons, the striking-distance queries, 16 months of named queries, and the sitemap status.
The property string and a token that refreshes on its own
A dated folder with one JSON file per report and a meta file naming the windows
None. If the token is missing, the run stops before any call and says to sign in again.
Step 2 of 5
Inspect the sitemap
Reads the live sitemap and asks the URL Inspection API about every URL in it, fifty at a time: indexed or not, the coverage state Google gives, the canonical it chose, the last crawl. Skipped with a flag when short on time.
The live sitemap, about 180 URLs
inspect-sitemap.json, one verdict per URL
None. A URL that answers “Internal error” is recorded as an API error and inspected again the following week.
Step 3 of 5
Summarise
Finds the previous snapshot folder and writes the four numbers beside it, then the category queries and the pages that caught them, the brand queries, the marketing pages’ impressions, what entered and left the index, the non-brand queries in positions 5 to 20, and the pages up and down.
This week’s folder and the previous one
summary.md, with its window and the snapshot it is compared to in the first line
A person reads it. The first time a category query lands on a page built for it, they note which page and which query.
Step 4 of 5
Report
Puts the four numbers into the week’s report with one sentence of judgement. The whole summary is not pasted; the report is for reading.
summary.md
One line in the weekly report
The person running it writes the sentence.
Step 5 of 5
Resubmit the sitemap
After new pages go live, resubmits the sitemap through the API. Google has no endpoint behind its Request indexing button, so this is the only recrawl signal the readout can send; it never uses the Indexing API, which accepts only job-posting and live-event pages.
The sitemap URL
A new last-submitted date on the sitemap report
None. Whether Google fetched it shows in the next readout’s last-downloaded date.
Before you start
What you’ll need to bring
Company material
The site as a Search Console property you hold Full access to, and the list of category terms a buyer of what you sell would type.
Source material
Your sitemap, served and submitted to Google. The agent reads it, inspects every URL in it and resubmits it; it writes nothing on the site.
Platform account
A Google account with Full access to the property and a published OAuth client for the Search Console API. The sign-in happens once in a browser; after that the token refreshes itself. No password handed over.
Run environment
A machine with Node.js for the scripts and an agent runner that follows a written workflow. We use Claude Code. No browser is kept open.
Run log
Recent runs, as they happened
The full log is public and read-only. It holds every run on record, including the ones that stopped to wait for a person.
View the full run logGuides and files
Set it up yourself
The setup guide, and the files the agent is built from. You run it in your own environment, with your own accounts.
- 01
Runtime
- An agent runner that can follow a written workflow and run Node scripts — we use Claude Code.
- Node.js 20 or later, for the three scripts.
- 02
Browser setup
- None. Everything comes from the Search Console API over an OAuth sign-in done once; no report on this readout needs a browser.
- 03
Account setup
- A Google account with Full access to the site’s Search Console property. Owner is not needed.
- A Google Cloud OAuth client for the Search Console API, with the app published: while it sits in Testing, the sign-in expires every seven days.
- The refresh token kept in a file outside the repository; it refreshes on its own after that.
- 04
Configuration
- The property string, copied exactly: a domain property (sc-domain:example.com) and a URL-prefix property (https://example.com/) are two different properties, and passing one where the account holds the other reads like a permissions error.
- The list of category terms a buyer of your product would type, and the spellings of your own name. Keep the category list identical to the one your Bing readout uses.
- The folder the weekly snapshots go to.
- 05
First run
- Pull once and check that the 28-day clicks and impressions match the Search Console dashboard for the same window.
- Open the sitemap report and confirm its last-downloaded date is moving; the indexed count it shows has stayed at zero for months and is not the number to read.
- Inspect the sitemap once and note the daily quota it used, about a tenth of the 2,000 a day.
SKILL.md
Workflow · Markdown. The steps above, the definitions and the known pitfalls, as the runner reads them.
pull.mjs
Script · Node. Pulls the eight Search Console reports and inspects every sitemap URL into one dated folder.
summarize.mjs
Script · Node. Writes summary.md beside the previous snapshot.
lib.mjs
Script · Node. The OAuth client, the token refresh and the API calls the other two share.
Not packaged for public download yet. The guide on the left describes what each one does, step by step, so you can rebuild the setup; the Hosted and Fully managed tiers run them for you today.
Rather have us run it?
Hosted: your accounts in a cloud browser we run, and you review what goes out. Fully managed: we set the strategy and run the agents.
Good to know
Where it stops and asks for you
- The token is missing or revoked. The pull stops before any call and says to sign in again; nothing is written to the snapshot folder.
- The property string is the wrong shape. Every call answers permission denied. The skill says to list the sites the account holds and copy the string exactly rather than guess at scopes.
- URL inspection answers “Internal error” for one URL. The verdict is recorded as an API error, the run goes on, and the URL is inspected again the following week.
- A week’s numbers moved by less than 2x. The summary says it is inside the noise band. Nothing on the site is changed on the strength of one week.
Risk notice
What to watch for
- Weekly clicks on a site this size wander between 2 and 11; a single-week change under 2x is noise and the summary says so. Changing a page because one week fell is the mistake this readout exists to prevent.
- URL inspection occasionally answers “Internal error” for one URL. The summary marks it as an API error and it clears the following week; nothing is retried blind.
- The Indexing API accepts only job-posting and live-event pages; submitting ordinary pages through it breaks its terms, so the agent never does. Resubmitting the sitemap is all it sends.
FAQ
Questions about this agent
Every call answers “permission denied”.
Nine times out of ten the property string is the wrong shape. List the sites the account holds and copy the string exactly, trailing slash or sc-domain: prefix included.
This week’s numbers look low on the last days.
Search Console finalises two to three days late. The readout’s windows end three days back for that reason; quote the dates it used, not the ones you asked for.
The query table adds up to far less than the site total.
Google withholds rare queries to protect the people who typed them. The gap is expected and is not lost traffic.
Can it ask Google to index a new page?
No. There is no API behind the Request indexing button. Resubmitting the sitemap is the only recrawl signal the API can send, and it is the last step of every readout that follows a new page.
Would you rather we ran this agent for you? There is a managed service for that.
Talk to us