Connect Google Search Console

A workspace connects one Google account, read-only. Each site is matched to the Search Console property for its domain, and a background sync copies Google's figures into StepMetrics. The Search page and the get_search_console MCP tool then show Google's side of each page (searches, times shown, clicks, position) beside what the visitors Google sent did on the site (stayed, converted).

Connecting

The quickest way is Continue with Google on the sign-in screen. One Google screen signs you in and grants read-only Search Console access; your workspace is created with a site for each property you can read, and Google's search data starts copying at once. Signing in that way with an account you already have links it to Google and connects the first workspace you manage that has no Google yet.

From the dashboard instead:

1. An owner or admin opens Search in the dashboard and chooses Connect Google Search Console.
2. Google's consent screen asks for read-only Search Console access and the account's email address.
3. Back on the Search page, every site whose domain matches a property is linked and starts copying. A site with no match, or the wrong match, gets a property from the menu in its row.
4. The first copy takes a minute or two and reaches back 90 days by default (searchConsoleBackfillDays, 7 to 480). It is refreshed every six hours.

Agents read the same report with get_search_console; connecting is the only step that needs a person.

If your site is not in Search Console yet

A site with no property is the commonest reason for no search data: it was never added to Search Console, it was added but never verified, or it is there under a different Google account. StepMetrics cannot add or verify a property for you (the connection is read-only, and Google checks ownership against the site itself), so the Search page tells you which of the three it is and what to do. Before you connect Google, the same steps sit behind "Not in Google Search Console yet?" under the Connect button; your agent gets them from get_search_console.

1. Open Google's add-property screen signed in as the account you connect to StepMetrics. Under Domain, enter your domain and continue. That creates the Domain property sc-domain:example.com, which covers http and https, with and without www. If you cannot edit DNS, choose URL prefix with https://example.com/ instead.
2. Verify ownership. For a Domain property Google shows a TXT record to add at your DNS provider; add it exactly as shown and press Verify. DNS changes can take from minutes to a few hours to be seen, and Google lets you press Verify again. For a URL-prefix property you can instead paste Google's HTML tag into the <head> of your home page, or upload its HTML file.
3. Come back to the Search page, or ask your agent for the search report. The site is linked as soon as the property is readable, without reconnecting Google, and its data starts copying. Google usually shows a new property's first data a day or two after verification.

If the site is already in Search Console under a different Google account, do not add it again: on that property open Settings, then Users and permissions, and add the connected account with Full or Restricted permission. Restricted is enough to read. The Search page checks the site's DNS and home page for an earlier Google verification and says so when it finds one, so you know which of the two paths you are on. A property the connected account added but never verified is named too, with "not verified yet", so the missing step is verification rather than adding it.

How a site is matched

In order: the site's Domain property (sc-domain:example.com), then URL-prefix properties for the host (https before http, bare before www), then a Domain property for a parent domain. A Domain property covers every host under it, so its rows are narrowed to the site's own host before they are stored. A property chosen by a person is kept across reconnects, and so is "Not linked". Changing a site's property deletes what it copied from the old one. A site still waiting for a property is matched again whenever the Search page or an agent looks, so adding it to Search Console later links it without a reconnect.

Reading the numbers

• Days are Google's: Pacific Time calendar days on both sides, so a day's clicks and a day's visits cover the same 24 hours.
• Visits from Google are visits in the search channel from a Google host or the Google app, paid clicks excluded. A visit converted when it recorded one of the site's conversion events.
• Google's clicks and visits from Google do not match and are not forced to: blocked trackers, and Google counting differently, both move them apart.
• The query table leaves out searches Google considers too rare to report, so it sums to less than the totals.
• Days Google has not reported yet are null, never zero. Days Google has not finalised are marked and fetched again on the next sync.

Brand terms

Set the words that mean someone searched for the site by name ("stepmetrics", "step metrics") on the Search page, or with set_search_brand_terms from an agent with an edit key. Each term matches as whole words, ignoring case. With terms set, the report adds a branded, non-branded and unlisted split for the window and the one before, and a branded search is never a near-first-page suggestion. Without terms the split is null and a note says so.

Suggestions

Five rules, each needing minimum evidence (searchConsoleMinImpressions, default 200; searchConsoleMinVisits, default 20). They say where to look, not why.

Marking a change and reading the review

A finding in an SEO audit may be open, dismissed or change deployed, with a note, from the Search page or with set_seo_finding_action. A deployed change is your report, not an automated verification. The original finding and its observation date are kept. The review excludes the deployment day and compares the 14 and 28 complete Pacific days before and after, using stored Google page totals: clicks, impressions, click rate and position. Stale, partial or low-volume data yields awaiting_data or insufficient_data; missing page evidence in either window is no_data. A Google update inside the window is named as an overlap. Reviews are computed when the report is read, so they fill in as Google's data arrives.

Audits

On the Search page, select a site and choose Run audit; agents use run_seo_audit and set_seo_audit_schedule with an edit key, and read results with get_seo_audit. An audit crawls up to 50 pages by default (100 at most) with a two-minute crawl budget, executes no JavaScript and sends no cookies, inspects up to 20 URLs through Google's URL Inspection, and reports real-visitor Core Web Vitals. Weekly audits are off until you turn them on. Manual audits have a one-hour cooldown per site. Findings carry severity, URL, evidence and a suggested action. There is no score.

Every site at once

The All Sites view of the Search page, GET /v1/search and the search section of get_portfolio show every site's Google figures side by side for the window and the one before. A site that is not linked, still copying or broken carries its state and no numbers.

When something breaks

• Google stops accepting the token: the connection is marked broken, syncing stops, a search_console alert goes out once, and the Search page asks for a reconnect. Copied data stays readable.
• The account loses access to one property: that site's row says so, and other sites keep syncing.
• Google unreachable or rate limiting: the sync records the reason and retries in an hour.

Disconnecting Google deletes audit snapshots and change records and disables weekly auditing; changing a site's linked property deletes its old audit evidence.

What the search report is for