Google Search Console is where organic search data lives, but it's been trapped in Google's UI black hole — until now. The Search Analytics API unlocks impression, click, and average-position metrics dimensioned by query, page, device, and country. Velocity X pulls this data into your SLT dashboard daily, unifies it with GA4 and Meta Ads, and surfaces the queries driving the most visibility. Here's how to wire it up and handle the lag.
OAuth Scopes and Property Selection
GSC uses Google OAuth with two scopes: webmasters.readonly (read Search Analytics) and webmasters.resource.readonly (list properties). On first setup, Velocity X requests both and stores the long-lived refresh token in Postgres. Users then see a dropdown listing every GSC property they own — most have one; large agencies have 50+. Each property has a separate resource ID (e.g., sc-domain:example.com for domain vs. https://example.com/ for URL prefix). Velocity X saves the selected property ID alongside the refresh token so future queries hit the right resource.
GET https://www.googleapis.com/search/all/sitemap
?siteUrl=sc-domain:example.com
&access_token=YOUR_TOKENSearch Analytics Queries — Dimensions and Date Ranges
The Search Analytics endpoint returns aggregated metrics across three dimensions: query, page, and device (plus country and search type). Velocity X queries the last 90 days daily at 03:00 UTC with row_limit=10000 (the max), start_date=90d_ago, and end_date=3d_ago. That 3-day lag is non-negotiable — Google's servers are still processing clicks and impressions up to 72 hours old. Request one day ahead and your data is incomplete by 30–50%.
POST https://www.googleapis.com/webmasters/v3/sites/sc-domain:example.com/searchAnalytics/query
{
"startDate": "2026-06-09",
"endDate": "2026-06-09",
"dimensions": ["query", "page", "device"],
"rowLimit": 10000,
"startRow": 0
}Each row returns impressions, clicks, ctr, and position (average rank on SERP). Store these in a Supabase table keyed by property + query + page + date so you can slice by landing page, segment by device, or rank queries by click volume. The row limit means queries with 10k+ result rows are truncated; pagination via startRow is slow but necessary for SEO-heavy sites.
The 3-Day Lag and Data Lag Handling
This is the gotcha nobody mentions: GSC data is delayed 3 days minimum. Query June 12 and you see data through June 9. This breaks real-time dashboards but it's not a bug — Google's attribution and click-counting happens asynchronously. Velocity X works around this by querying a rolling 90-day window daily and _backfilling_ — we re-pull the last 5 days every run because Google occasionally adjusts historical data (click fraud corrections, IP filtering updates). The dashboard shows "data through June 9" in a grey badge so users don't misinterpret it as live. For SaaS teams chasing daily wins, this is a culture shock; for serious SEO, this lag forces you to think in trends, not ticks.
GSC vs. GA4 — Different Identity Models
This is critical: GSC counts organic clicks at the search-result level; GA4 counts pageviews after users land. A query can show 100 clicks in GSC but only 60 sessions in GA4 — some users don't fire GA4, some have blocked tracking, and some visit multiple pages in one session. Never use GSC and GA4 interchangeably. Use GSC for "which queries are we ranking for" and "what's our click-through rate"; use GA4 for "what do users do after landing". Velocity X surfaces both side-by-side so you can see the drop-off.
Indexation and Coverage
Search Analytics only shows queries where you're ranking and getting impressions. No impressions = no rows. If a page isn't indexed or isn't ranking for any queries, it won't appear. This is a feature, not a bug — it forces you to ignore the 1000s of no-traffic pages and focus on the 50 that matter. Pair this with the Coverage API (same OAuth scope) if you need to debug indexation issues; Velocity X uses it during site migrations to verify all URLs re-indexed after the move.
Frequently Asked Questions
Why do clicks in GSC and GA4 never match?
Different identity models. GSC counts clicks at the SERP; GA4 counts pageviews after landing. Some users don't fire GA4. Some visit multiple pages in one session but GA4 reports it as one session, while GSC counts each initial click. Use both but don't reconcile them.
Can I pull real-time GSC data?
No. The 3-day lag is hardwired into Google's data pipeline. Workaround: use the rank-tracking tools (Ahrefs, SEMrush, Moz) which update daily, but they cost $$$.
How do I handle pagination for queries over 10k rows?
Use startRow in increments of 10k. If your site has 50k+ unique queries, you'll need 5 API calls per query to get them all. Cache aggressively and batch the calls.
What's the difference between domain and URL-prefix properties?
Domain = all subdomains + all protocols (http, https). URL-prefix = exact. Use domain unless you have multiple subdomains with different content strategies.
The Bottom Line
GSC Search Analytics API is the SEO integration Google should have built in 2015. Scopes are clean, data is real, and the 3-day lag is defensible — it's Google being honest about data pipeline latency instead of faking real-time. Velocity X bakes this into your SLT dashboard and surfaces the queries, pages, and positions that matter, so you can stop toggling tabs and start acting on data. See pricing or read more about unified marketing analytics across GSC, GA4, and Meta.