Skip to main content
Use the analytics endpoints to notice search movers, diagnose a URL (which queries it ranks for, and whether it is indexed), then create content. Search Analytics numbers come from the warehouse. The only live Google read is URL Inspection, and it runs only on page performance.

​
Who can call this

  • Public API: analytics:read plus API Access (Teams V2 or higher). Existing keys do not pick up the new scope automatically — add analytics:read in the dashboard or create a key from a Read / MCP preset.
  • MCP: granted rooftops need Teams or higher with API Access. Tools use the same warehouse as REST.
GOOGLE_SERVICES is required for Search Console and GA4 warehouse reads. A missing plan is 402 / upgrade-required. A rooftop that has never connected Search Console is connected: false — do not treat an API Access denial as disconnected.

​
Notice → diagnose → create

  1. GET /analytics/search/snapshot and GET /analytics/search/alerts (MCP: get_search_snapshot, get_search_alerts, or get_dealer_briefing).
  2. GET /analytics/search/opportunities and GET /analytics/search/gaps for what to write. Keep GET /content-intelligence for nightly Content Intelligence recommendations — those are a different pipeline.
  3. GET /analytics/pages/performance?page_url=… (MCP: get_page_performance) for query×page plus URL Inspection (24h cache).
  4. GET /analytics/search/create-brief, then create with IdeaClouds or Content.
Pulse (GET /analytics/search/pulse) is REST-only. Group site lists can include pulse; there is no MCP pulse tool.

​
Warehouse vs live Google

Do not call Search Analytics API v2 from this product. Listing endpoints do not inspect URLs. GET /content/{id} may attach a cached inspection strip; it never triggers a live inspect.

​
50k query×page cap

Each GSC connection syncs up to 50,000 query×page rows per search type (web and image) per day. Snapshot, query lists, and page lists read daily top_queries / top_pages breakdowns for the lookback (so 28-day and 90-day windows differ). Page diagnose, movers, gaps, and questions still read query×page rows (5,000-cell sample ordered by impressions) and can miss tail queries. Treat those as a bounded sample, not every Google row.

​
Search questions vs gen-AI exhaust

GET /analytics/search/questions (MCP: get_search_questions) buckets warehoused query strings: interrogatives, near-me, and gen-AI exhaust (queries that look like assistant-style phrasing). Those strings are keywords for IdeaClouds. They are not Playbook AI visibility, ranking in generative answers, or a live Google generative report.

​
Keyword gap vs. a competitor

GET /analytics/seo/keyword-gap (MCP: get_keyword_gap) returns the SE Ranking comparison against the competitor last selected in Clarity’s SEO > Keyword Gap widget. Each keyword is either missing (the competitor ranks and the dealer does not) or behind (the competitor ranks higher). Rows are ordered by opportunityScore (search volume scaled by ease and by how far ahead the competitor is), and limit caps the list (default 25, max 100). The endpoint reads stored data only and never starts a new comparison. connected: false means nobody has compared a competitor yet: pick one in Clarity first. Each new comparison replaces the previous one, so there is no gap history. To close a gap, pass the keyword to get_create_brief or create_ideacloud.

​
Endpoints

All of these require analytics:read. See analytics:read for the full table. Typical query: lookback_days (28 or 90). Page performance also requires page_url.

​
MCP tools

The same facts are MCP tools (get_search_snapshot, listings, opportunities, gaps, changes, decay, questions, keyword gap, alerts, create-brief, page performance, traffic, demand). Cards render for snapshot, opportunities, gaps, changes, alerts, create-brief, and page performance. Connect with OAuth and a saved rooftop grant as in Hrizn MCP.
Last modified on October 22, 2026