#Google Search Console

X3 reads your Google Search Console data – search queries, pages, countries and devices with clicks, impressions, click-through rate (CTR) and average position – and puts it next to what happens on your site: which pages organic Google visitors land on and how many of them become leads. The connection is read-only: X3 only lists your properties and reads search analytics; it never changes anything in Search Console.

#Connect

In the dashboard: Einstellungen › Google Search Console › Mit Google verbinden. Connecting needs project:admin and a dashboard user (it is an OAuth sign-in, confirmed with your password).

1. Sign in with the Google account that has access to the property.
2. Choose the property. Properties matching your tracked domains come first; unverified properties cannot be read and are shown greyed out.
3. Choose how far back to load (1–16 months, default 16 – Google keeps 16 months). The first sync starts immediately and runs in the background, newest month first, with live progress („Erster Abgleich läuft · 3 von 16 Abschnitten").

Over the API:

POST /v1/projects/{project}/search-console/connection          → { redirectUrl }   (user session, sudo)
POST /v1/projects/{project}/search-console/connection/complete  { nonce, connectedAccountId, status }
GET  /v1/projects/{project}/search-console/sites                → properties of the Google account
PUT  /v1/projects/{project}/search-console/property            { "siteUrl": "sc-domain:example.com", "backfillMonths": 16 }

The OAuth callback is verified: the nonce, the signed-in user who started the connection and the connected account must match. Reloading the callback page is harmless.

#Sync

• Daily: once a day X3 re-reads the last 4 days (Google still corrects them) and fills any gap.
• Now: POST /v1/projects/{project}/search-console/sync (optional from/to) – „Jetzt abgleichen" in the dashboard. The request answers 202 at once with the queued run; while a run of the same window is open, a second request adds nothing.
• Runs: GET /v1/projects/{project}/search-console/runs lists runs with done/total days, state (queued, running, ok, partial, error, skipped) and a readable label.

Google publishes a day after about 2–3 days, so the newest days are empty at first. Search Console days are Google's (Pacific time) days; X3 ranges are days of your project's time zone – at the edges of a range the numbers can differ by a few hours of traffic.

#Reports

GET /v1/projects/{project}/search-console/report?dimension=query&preset=30d&cmp=previous
GET /v1/projects/{project}/search-console/report?dimension=page&sort=x3Leads:desc
GET /v1/projects/{project}/search-console/report?dimension=page&query=preise%20tracking
GET /v1/projects/{project}/search-console/timeseries?preset=90d&country=DE

• dimension: query, page, country, device or date. Page rows use the canonical X3 path (same rules as your tracking: host prefixes, redaction, exclusions). X3 never stores the raw URL of your own pages: personal paths are redacted (or, with personal mode exclude, left out like excluded paths – the site totals still count them). URLs on hosts you do not track are kept as origin + path without query string or fragment (personal rules applied) and have no X3 numbers.
• Totals come from Google's site totals and include anonymized queries – the query rows therefore add up to less than the total. That is how Search Console works, not a gap.
• Narrowing: query, page (X3 path or full URL), country (ISO code like DE), device (desktop, mobile, tablet). Google delivers queries and pages combined, countries and devices only on their own or per day – other combinations answer 400.
• Table parameters: sort=clicks:desc,position:asc (up to three), q= (search in the label), f.<field>=<op>:<value> with gte, lte, between (numbers; CTR as a fraction 0–1 like in the answers: f.ctr=gte:0.05 is 5 %, values above 1 answer 422), contains, eq, in; limit and cursor (nextCursor of the previous page). Unknown fields answer 422.

#Brand and opportunities

GET /v1/projects/{project}/search-console/opportunities?preset=90d

• Brand split: clicks and impressions of searches with the company name („Kennen Dich schon“) and without („Finden Dich neu“). Brand terms come from settings.traffic.brandTerms ([{ "term": "nordlicht studio", "ambiguous": false }]), else they are prefilled from the project name and domains. An ambiguous term ("ambiguous": true, „mehrdeutig“ – a short name that mostly means something else) counts as brand but leaves the click rate, so it cannot make the brand look ignored.
• Chancen: „Fast oben, aber kein Klick“ (non-brand, at least 50 impressions, position up to 5, click rate below the curve), „Knapp unter der ersten Seite“ (position 8 to 15, at least 30 impressions) and „Neu bei Google gefunden“. Each comes with a title and a sentence to show.
• Page aliases: Search Console reports the address Google shows (/), X3 the page the visitor lands on after the redirect. settings.traffic.pageAliases maps them explicitly ({ "/": ["/de", "/en"] }); without it X3 uses the observed language roots.
• Clicks are not people: Google counts clicks in the results, X3 counts visits on your site, so the numbers differ. X3's search visits include Bing and other engines (channel group search, see Visitors and traffic).

MCP: search_console_opportunities.

#States

GET /v1/projects/{project}/search-console returns the state every view uses, a one-line message and the next action:

Actions that need a working connection answer connector_missing, connector_expired or connector_permission_denied (see errors). Disconnecting (DELETE …/search-console/connection) keeps the stored data; ?purge=true deletes it too. Connecting, choosing a property, syncing and disconnecting are written to the audit log.

stale, expired, permission_denied and error also open the alert search_console_problem (bell and „Braucht Dich“, alerts) with a link to the settings. It is checked again right after every connection or property change and closes itself once the state is fine again.

#In the dashboard

• Quellen › Organische Suche: totals with comparison, clicks and impressions per day, and tables for queries, pages, countries and devices (sortable, filterable, columns selectable, CSV export). A click on a query shows its pages, a click on a page its queries.
• Verhalten › Seiten: Google clicks, impressions and position next to each page, and the top queries of the selected page.
• Viewers see the numbers; only project admins connect, change the property or start a sync.

#MCP

search_console_status, search_console_report and search_console_sync – see MCP tools.

#Self-hosting

Create an auth config for the Composio toolkit google_search_console and set COMPOSIO_AUTH_CONFIG_GOOGLE_SEARCH_CONSOLE (plus COMPOSIO_API_KEY) – see environment. Without it the feature shows "nicht eingerichtet".