> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Search Console
> Connect Google Search Console to your Agents for live clicks, impressions, CTR, and ranking data
## 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](https://search.google.com/search-console) (any permission level — Owner, Full, or Restricted)
* An Aster **admin** to connect the integration (the connection is shared org-wide)
## Setup Guide
Navigate to **Control Hub > Integrations**, locate the **Google Search Console** card, and click **Connect**. You'll be redirected to Google to sign in.
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.
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 (default 1,000) 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.
* **Large results spill to a CSV:** when a query returns more rows than fit comfortably inline, the full row set is written to a CSV attachment (columns: your dimensions + `clicks`, `impressions`, `ctr`, `position`) and the inline payload is truncated to a token budget. The CSV is auto-mounted into the [`execute_python`](/tools/execute_python) sandbox at `/home/user/`, so an agent can diff two 28-day windows or rank biggest movers in pandas without overflowing its context.
## 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](https://myaccount.google.com/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.
## Related
* [Google Analytics 4](/integrations/google-analytics) — live traffic, engagement, conversion, and revenue data. Shares the same one-click Google OAuth plumbing.
* [Run Code](/tools/execute_python) — analyze large Search Analytics pulls (the CSV spillover attachment) with pandas: period-over-period diffs, drop detection, ranking.