Gcloud Search Console

Google Search Console via gcloud

Pull Search Console (GSC) data from the CLI using the official REST API at searchconsole.googleapis.com, authenticated via gcloud Application Default Credentials.

Prerequisites

1. gcloud is installed and a project is set. If not, run the gcloud-setup skill first.
2. The Google account being used owns or has access to the site in Search Console. Check at https://search.google.com/search-console — if the site is not listed there, this skill cannot help; the user needs to verify the property first.
3. The Search Console API is enabled on the project:

``bash gcloud services enable searchconsole.googleapis.com ``

Step 1: Authenticate ADC with the Search Console scope

The scope is https://www.googleapis.com/auth/webmasters.readonly (read-only) or https://www.googleapis.com/auth/webmasters (read/write). Read-only is sufficient for querying performance data.

⚠️ gcloud auth login --scopes=... does NOT work. Use application-default login:

SCOPES="openid"
SCOPES="$SCOPES,https://www.googleapis.com/auth/userinfo.email"
SCOPES="$SCOPES,https://www.googleapis.com/auth/cloud-platform"
SCOPES="$SCOPES,https://www.googleapis.com/auth/webmasters.readonly"
gcloud auth application-default login --scopes="$SCOPES"

When the browser opens, log in with the Google account that has access to the site, and check every scope box on the consent screen (if cloud-platform is unchecked the ADC will be unusable).

Step 2: List accessible sites

TOKEN=$(gcloud auth application-default print-access-token)
PROJECT=$(gcloud config get-value project)

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "x-goog-user-project: $PROJECT" \
  https://searchconsole.googleapis.com/webmasters/v3/sites | jq

Sample output:

{
  "siteEntry": [
    {"siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner"},
    {"siteUrl": "https://example.com/", "permissionLevel": "siteOwner"}
  ]
}

Site URL formats

• Domain property (covers all subdomains + schemes): sc-domain:example.com — URL-encode the colon as %3A when placing it in a URL path: sc-domain%3Aexample.com.
• URL-prefix property: the full URL, e.g. https://example.com/. URL-encode the whole thing with jq -rn --arg s "$SITE" '$s|@uri' or python -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SITE".

Step 3: Query search analytics

Endpoint: POST /webmasters/v3/sites/{siteUrl}/searchAnalytics/query.

SITE="sc-domain:example.com"
SITE_ENC=$(python3 -c "import urllib.parse,sys;print(urllib.parse.quote(sys.argv[1],safe=''))" "$SITE")

curl -s -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  -H "Content-Type: application/json" \
  "https://searchconsole.googleapis.com/webmasters/v3/sites/${SITE_ENC}/searchAnalytics/query" \
  -d '{
    "startDate": "2026-04-07",
    "endDate":   "2026-04-14",
    "dimensions": ["query"],
    "rowLimit": 25
  }' | jq

Request body fields

| Field | Notes | |---|---| | startDate, endDate | YYYY-MM-DD. GSC data has ~2-day lag; yesterday's data may be missing. | | dimensions | Array. Any combination of query, page, country, device, date, searchAppearance. | | rowLimit | Max 25,000 per call. Default 1,000. | | startRow | For pagination. Increment by rowLimit. | | dimensionFilterGroups | Filter results. See examples below. | | type | web (default), image, video, news, discover, googleNews. | | dataState | final (default) or all (includes fresh, unsettled data). |

Common query recipes

Top queries, last 7 days:

{"startDate":"2026-04-07","endDate":"2026-04-14","dimensions":["query"],"rowLimit":25}

Top pages, last 28 days:

{"startDate":"2026-03-17","endDate":"2026-04-14","dimensions":["page"],"rowLimit":50}

Daily click/impression series:

{"startDate":"2026-03-17","endDate":"2026-04-14","dimensions":["date"]}

Queries that contain "llm" and rank in top 10:

{
  "startDate":"2026-03-17","endDate":"2026-04-14",
  "dimensions":["query"],
  "dimensionFilterGroups":[{
    "filters":[
      {"dimension":"query","operator":"contains","expression":"llm"}
    ]
  }],
  "rowLimit":100
}

Performance for a specific page:

{
  "startDate":"2026-03-17","endDate":"2026-04-14",
  "dimensions":["query"],
  "dimensionFilterGroups":[{
    "filters":[
      {"dimension":"page","operator":"equals","expression":"https://example.com/some-page/"}
    ]
  }],
  "rowLimit":100
}

Filter operators: equals, notEquals, contains, notContains, includingRegex, excludingRegex.

Step 4 (optional): Other Search Console endpoints

| Goal | Method & Path | |---|---| | List sitemaps | GET /webmasters/v3/sites/{site}/sitemaps | | Submit a sitemap | PUT /webmasters/v3/sites/{site}/sitemaps/{feedpath} (needs webmasters scope, not read-only) | | Inspect a URL | POST /v1/urlInspection/index:inspect on https://searchconsole.googleapis.com — body: {"inspectionUrl":"...","siteUrl":"..."} |

Step 5 (optional): Bulk export to BigQuery

For large date ranges (API caps at 50k rows per query and samples heavily above that), use Search Console's native BigQuery bulk export:

1. In Search Console UI → Settings → Bulk data export → link to your GCP project.
2. Google creates a dataset searchconsole in that project and writes daily snapshots.
3. Query with bq:

``bash bq query --use_legacy_sql=false ' SELECT query, SUM(clicks) AS clicks, SUM(impressions) AS impressions FROM YOURPROJECT.searchconsole.searchdatasite_impression WHERE data_date BETWEEN "2026-04-01" AND "2026-04-14" GROUP BY query ORDER BY clicks DESC LIMIT 50 ' ``

One-liner "is this working" check

curl -s \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "x-goog-user-project: $(gcloud config get-value project)" \
  https://searchconsole.googleapis.com/webmasters/v3/sites | jq -r '.siteEntry[]?.siteUrl'

If this lists the user's sites, the skill is fully working.

Troubleshooting

| Symptom | Cause | Fix | |---|---|---| | accessNotConfigured / SERVICE_DISABLED | API not enabled on quota project | gcloud services enable searchconsole.googleapis.com | | API requires a quota project | Missing header | Add -H "x-goog-user-project: $(gcloud config get-value project)" | | Request had insufficient authentication scopes | ADC created without webmasters.readonly | Re-run Step 1 with the correct scope list | | User does not have sufficient permission for site 'X' | Logged-in Google account lacks GSC access to that property | Log in as the owning account, or have the owner add this account in Search Console → Settings → Users and permissions | | Empty rows in the response | No data for that dimension/date range, OR data lag (GSC is ~2 days behind) | Widen the date range, or set "dataState":"all" | | 400 invalid filter | Wrong operator name or malformed body | See the filter operator list above |

---

Part 2 — Search Console Operator Playbook (2025-2026)

Everything below is for analysis and action, not for calling the API. Use it once you can pull data (Part 1) to decide what to pull, why, and what to do with it.

A. Ranking model — what Google actually weighs

| Signal | How measured | Weight | What to watch | |---|---|---|---| | Relevance | Neural matching + RankEmbed vectors; BERT/DeepRank re-ranks top 20-30 | Must-pass gate | Query-doc semantic match, entity overlap, intent class | | Helpful content / site quality | Sitewide classifier, folded into core March 2024 | Very high; sitewide demotion possible | Originality, depth, firsthand experience, % unhelpful pages | | E-E-A-T | Rater guidelines + off-site entity signals | High across all topics (not just YMYL) | Named authors + bios + sameAs, cited sources, editorial mentions | | Navboost (click signals) | 13-month rolling GoodClicks / BadClicks / LastLongestClicks, per device × country × language | Top-tier (per Pandu Nayak testimony) | SERP CTR vs position, dwell, pogo-stick back-to-SERP | | Backlinks | SpamBrain-filtered graph; topical relevance > DR | Still major but bar raised | Editorial, body-of-page, topically matched links; avoid PBNs/anchor spam | | Brand mentions (linked + unlinked) | Corroboration/co-occurrence | Rising fast; now ~3× links for AI visibility | Ahrefs 75k brands: mentions Spearman 0.664, links 0.218 | | Core Web Vitals | CrUX p75 field data, 28-day window | Tiebreaker; heavier post-Dec 2025 CU | LCP ≤2.5s, INP ≤200ms, CLS ≤0.1 | | UX / ad experience | clutterScore, interstitial policy demotions | Can single-handedly tank a site | Ad density, popups, unclosable video, intrusive interstitials | | Freshness (QDF) | Query-deserved-freshness classifier | Query-dependent | Real content diffs, not date-swapping | | HTTPS / mobile | Booleans | Baseline | Valid cert, mobile-usable (mobile-first indexing default) |

Key shift: ranking is comparative. Your page is scored against the live competing set for each query — rankings can drop with zero on-site changes.

B. Core algorithms / systems (2025-2026 state)

• Helpful Content system — continuous, sitewide. Integrated into core updates since March 2024. Tanks scaled/fringe/AI-at-scale editorial. Recoveries are slow and land on Core Update cycles.
• SpamBrain / spam updates — Aug 2025 + Oct 2025 targeted scaled content abuse and site-reputation abuse (a.k.a. "parasite SEO"). Mostly silent devaluation now; manual actions are the exception.
• Core updates — 2025: March, June, December. 2026: Feb Discover-only, March (completed Apr 8, 2026). Unannounced "tremors" run between announced CUs — don't panic-edit mid-rollout.
• Navboost — user-interaction re-ranker; domain-level click patterns contribute to site-wide quality signals.
• Neural matching / RankEmbed / BERT / DeepRank — semantic retrieval + top-N re-ranking. DeepRank decides positions 1-10.
• Reviews system — continuous; rewards firsthand testing, original photos/video, pros/cons, comparisons; tanks aggregator rewrites.
• AI Mode / AI Overviews — powered by Gemini 3 Pro (AI Mode since Nov 2025, Gemini 3 Flash default Dec 2025). Query fan-out: one user query decomposes into multiple sub-queries retrieved and synthesized (confirmed Google I/O 2025).
• Twiddlers — post-retrieval re-rankers (QualityBoost, freshness, diversity) that can promote/demote after main scoring.

C. GSC reports — what each exposes and what to do with it

Performance → Search results (the workhorse)

Metrics and real meaning:

| Metric | Real definition | Watch out for | |---|---|---| | Impressions | URL appeared in SERP for query, even below fold; AIO citations count | Sept 2025 num=100 removal + a May-Oct 2025 logging bug inflated/deflated impressions — don't over-read mid-2025 deltas | | Clicks | User left SERP for your URL | Multi-click sessions aggregate to 1 | | CTR | clicks ÷ impressions | Noisy at low volume; SERP features (AIO, snippet, packs) consume clicks | | Average position | Impression-weighted mean of topmost rank per query-page-day-country-device | Max 1 position per scope/day. Adding long-tail can lower average while clicks rise. Directional only. |

• Data lag ~2-3 days. "Last 24 hours" view gives provisional same-day.
• UI exports cap at 1,000 rows; API at 50,000 per call. For unsampled data use BigQuery bulk export.
• Tabs: Queries / Pages / Countries / Devices / Search appearance / Dates. "Compare" mode is the main diagnostic lens.

High-ROI query-level recipes:

| Goal | Filter / view | |---|---| | Striking-distance keywords | Queries → Position 8.0-20.0, sort by impressions desc | | High-impression low-CTR | Queries → Impressions > 500, sort CTR asc (cross-check for AIO on the SERP) | | Declining queries | Compare last 3mo vs previous, Queries sort Click-diff asc | | Rising queries | Compare, sort Click-diff desc — expand coverage | | Cannibalization | Filter 1 query → switch to Pages tab; multiple URLs with traffic = consolidate | | Brand vs non-brand | Regex filter on Queries — Doesn't match brand regex |

URL Inspection

• Indexed view = what Google has on file (coverage, canonical selection, last crawl, user-declared vs Google-selected canonical). Use for canonical mismatch forensics.
• Live test = Googlebot runs now (rendered HTML, screenshot, JS console). Does not evaluate quality/canonical/duplicate — only tech.
• Request indexing is rate-limited (~10-15/day). Don't use it as a bulk strategy — fix the root cause and update the sitemap.

Indexing → Pages (why URLs aren't indexed)

| Reason | Action | |---|---| | Crawled - currently not indexed | Quality signal. If spiking after a CU/HCU or on AI-content-heavy sites: prune thin/derivative pages, consolidate, improve E-E-A-T. Sudden spike on small site = possible hack. | | Discovered - currently not indexed | Crawl-budget / perceived low priority. Improve internal links from authoritative pages, faster server response, include in sitemap. | | Duplicate, Google chose different canonical | Audit canonical signals (hreflang, internal links, redirects, content similarity). | | Soft 404 | Return real 404/410 or add real content. Common on empty category/search pages. | | Excluded by 'noindex' | Audit — CMS plugins often add noindex inadvertently. | | Page indexed without content | JS rendering failure. Live-test and move critical content server-side. | | 5xx server error | Block-priority fix; audit logs, edge workers, capacity. |

Sitemaps

• Every URL in sitemap must be 200, canonical, indexable. Remove noindex/redirected URLs — they pollute discovery and dilute the report.
• Split sitemaps per content type (products/articles/categories) so Pages → "All submitted pages" pinpoints which segment fails.
• "Discovered URLs" ≠ indexed. Cross-reference via Pages report.

Experience → Core Web Vitals

• Source: CrUX field data, p75 per URL group, 28-day window. Lab data (Lighthouse/PSI) is for debugging only.
• A group's status = its worst metric. Fix at template level, not per URL.
• Report lag: ~28 days after fix before field data shifts. Use PSI per-URL for instant validation.
• Low-traffic URLs don't appear (insufficient CrUX samples).

Enhancements (rich results)

What's gone or restricted as of 2025-2026:

• HowTo — fully retired Sept 2023.
• FAQPage rich results — restricted to authoritative gov/health sites since Aug 2023 for Search display (but still high-value for AI answer engines — see Section E).
• Mobile Usability standalone report — retired Dec 2023; mobile signal surfaces only in URL Inspection.
• June 2025 simplification — Practice Problems, Nutrition Facts variants, Vehicle Listings nearby offers, TV Season Selector, Local Bikeshare, Today's Doodle phased out. BigQuery export fields for deprecated types return NULL after Oct 1, 2025; report/API support stops Jan 2026.

What invalidates a valid result: missing required field, malformed JSON-LD, markup not matching visible content, content behind unrendered JS, expired dates, wrong currency/units.

Security & Manual actions

Manual-action categories: user-generated spam, thin content, unnatural links to/from site, cloaking, sneaky redirects, pure spam, hidden text/keyword stuffing, sneaky mobile redirects, site reputation abuse (clarified Jan 2025 — noindex alone insufficient; moving to subdomain counts as evasion).

Reconsideration request must: admit violation, detail every remediation step, document outcomes (sample fixed URLs, removed link coun

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: extractumio
• Source: extractumio/extractum-skills
• License: MIT

Install and usage instructions live in the source repository linked above.