Skip to main content

​
Overview

The Google Search Console integration gives your agents live access to your Search Console performance data. Agents can pull clicks, impressions, CTR, and average position for any property the connected Google account can read — grouped and filtered however you need — to triage ranking drops, surface top queries, compare periods, and ground SEO work in real data instead of stale exports. Setup is one-click Google OAuth at the org level: an admin connects once, and every agent in the organization can query Search Console.

​
Prerequisites

  • A Google account that has access to at least one property in Google Search Console (any permission level — Owner, Full, or Restricted)
  • An Aster admin to connect the integration (the connection is shared org-wide)

​
Setup Guide

1

Connect Google Search Console in Aster Agents

Navigate to Control Hub > Integrations, locate the Google Search Console card, and click Connect. You’ll be redirected to Google to sign in.
2

Sign in with a Google account that has property access

Choose the Google account that can read your Search Console properties and approve the requested read-only access. Aster’s OAuth app is in Google’s production audience, so the refresh token is durable — the connection persists indefinitely unless someone revokes access. Tokens are stored server-side and redacted in API responses.
3

Add Tools to Your Agent

Edit your agent and enable List Search Console Sites and Search Analytics Query. The agent looks up the exact property siteUrl at runtime, then pulls performance data against it.

​
Available Tools

  • List Search Console Sites (gsc_list_sites) — Discover every property the connected Google account can read, plus the permission level on each. Agents grab the exact siteUrl at runtime instead of hard-coding it.
  • Search Analytics Query (gsc_search_analytics_query) — The workhorse. Pull clicks, impressions, CTR, and average position for a property over any date range (data goes back ~16 months).
    • Group by one or more dimensions: query, page, country, device, date, or searchAppearance.
    • Search type: web (default), image, video, news, discover, or googleNews.
    • Filter on any dimension with contains / equals / notContains / notEquals / includingRegex / excludingRegex, combined with AND-of-groups / AND-within-group logic for arbitrary precision.
    • Volume & freshness: up to 25,000 rows per call with offset-based pagination (start_row), and a data_state switch for live (all, fresh but may revise) vs finalized (final) data. aggregation_type controls auto / byPage / byProperty rollup.

​
Example Prompts

Once connected, agents can answer questions like:
  • “What were our top 20 queries last month, ranked by clicks?”
  • “Which pages lost the most impressions over the last 28 days vs the prior 28?”
  • “Give me CTR by device for the pricing page over the last 90 days.”
  • “Show me queries where we rank on page 2 (positions 11–20) with high impressions — the quick-win opportunities.”
The connection is shared by every agent in your organization and reads only the properties the connected Google account can access. Use agent-level tool permissions to control which agents can query Search Console.

​
Security Considerations

  • Read-only — the integration only requests read access to Search Console data; agents cannot modify your property or its settings.
  • Org-level connection — one admin connects once for the whole organization. Tokens never leave the server and are redacted in API responses; access tokens auto-refresh behind the scenes.
  • Grant the Search Console tools only to agents that need them.
  • Revoke any time — disconnect from the connection modal under Control Hub > Integrations, or revoke Aster’s access from your Google Account permissions.

​
Troubleshooting

  • The connected Google account doesn’t have access to any Search Console property. Add that account as a user on at least one property in Search Console (Settings → Users and permissions), or reconnect with a Google account that already has access.
  • The connection may have been revoked on the Google side. Reconnect from the Google Search Console card under Control Hub > Integrations.
  • Confirm the siteUrl matches exactly what List Search Console Sites returns (domain properties look like sc-domain:example.com; URL-prefix properties include the scheme, e.g. https://example.com/).
  • Very recent dates may be empty until Search Console finalizes them — try data_state: all for fresher (but revisable) numbers, or widen the date range.
  • The response flags when it returns the full row_limit. Paginate with start_row, or narrow the date range / add a filter group to reduce the result set.
  • Google Analytics 4 — live traffic, engagement, conversion, and revenue data. Shares the same one-click Google OAuth plumbing.