> ## Documentation Index
> Fetch the complete documentation index at: https://docs.consile.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference: Google Search Console

> The seven read-only tools in the GSC connector: arguments, return values and examples. Covers the shared siteUrl/date conventions, the raw Search Analytics passthrough and the reconnect error contract.

All tools are **read-only** and are called via `tools/call` over `POST /gsc/mcp`. You need an active Google Search Console subscription, and your authorized Google account must have access to the properties you query.

<Info>
  Endpoint: `https://mcp.consile.ai/gsc/mcp`. GSC is its own named connector with only its own tools. Tool names are namespaced `gsc__<tool>` in Claude/ChatGPT (the bare names are used here for readability). The connector is **multi-instance**: an extra connected instance is served under its own id (e.g. `gsc-2__<tool>`).
</Info>

<Warning>
  Every upstream call has a built-in **15-second timeout**; there is no other client-side rate limiting (Google's own API quotas apply upstream). Access tokens are refreshed silently on the read path; a revoked grant surfaces as `AccessTokenExpiredError` ("reconnect required", raised on a `401` from Google). See [Errors & limits](/developers/errors-and-limits).
</Warning>

## Common parameters

<ParamField path="siteUrl" type="string" required>
  A Search Console property. Either a URL-prefix property (`https://www.example.com/`) or a domain property (`sc-domain:example.com`). Get valid values with [`list_sites`](#list_sites).
</ParamField>

<ParamField path="startDate / endDate" type="string (YYYY-MM-DD)">
  Date range for the report. Must be the format `YYYY-MM-DD`. See [data freshness](/developers/errors-and-limits#data-freshness-google-search-console).
</ParamField>

***

## list\_sites

Lists the verified properties your account has access to.

**Arguments:** none.

<ResponseField name="sites" type="array">
  List of properties.

  <Expandable title="fields" />
</ResponseField>

<CodeGroup>
  ```json Request theme={null}
  { "name": "gsc__list_sites", "arguments": {} }
  ```

  ```json Result (payload) theme={null}
  {
    "sites": [
      { "siteUrl": "sc-domain:example.com", "permissionLevel": "siteOwner" },
      { "siteUrl": "https://shop.example.com/", "permissionLevel": "siteFullUser" }
    ]
  }
  ```
</CodeGroup>

***

## top\_queries

The most-clicked search queries for a property over a date range.

<ParamField path="limit" default="10" type="integer">
  Max number of rows. Integer between `1` and `25000`.
</ParamField>

<ResponseField name="queries" type="array">
  Rows sorted by clicks. Each item has `query`, `clicks`, `impressions`, `ctr` and `position`.
</ResponseField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "top_queries",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28",
      "limit": 5
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "queries": [
      { "query": "example keyword", "clicks": 421, "impressions": 9120, "ctr": 0.046, "position": 7.8 }
    ]
  }
  ```
</CodeGroup>

***

## top\_pages

The most-clicked pages for a property over a date range. Same arguments as [`top_queries`](#top_queries).

<ResponseField name="pages" type="array">
  Rows sorted by clicks. Each item has `page`, `clicks`, `impressions`, `ctr` and `position`.
</ResponseField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "top_pages",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "pages": [
      { "page": "https://example.com/", "clicks": 980, "impressions": 21340, "ctr": 0.046, "position": 5.1 }
    ]
  }
  ```
</CodeGroup>

***

## query\_performance

Clicks, impressions, CTR and position for **a single query**.

<ResponseField name="metrics" type="object">
  `clicks`, `impressions`, `ctr`, `position`. If the query has no data in the period, zeros are returned.
</ResponseField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "query_performance",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "query": "example keyword",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "query": "example keyword",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "metrics": { "clicks": 421, "impressions": 9120, "ctr": 0.046, "position": 7.8 }
  }
  ```
</CodeGroup>

***

## page\_performance

Like [`query_performance`](#query_performance), but for **a single page**. Use `page` (exact page URL) instead of `query`.

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "page_performance",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "page": "https://example.com/product",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "page": "https://example.com/product",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "metrics": { "clicks": 132, "impressions": 4010, "ctr": 0.033, "position": 9.4 }
  }
  ```
</CodeGroup>

***

## compare\_periods

Compares metrics between **two periods** with both absolute and percentage differences. Can be broken down by a dimension.

<ParamField path="dimension" type="string (enum)">
  Optional breakdown: `query`, `page`, `country`, `device`, `searchAppearance` or `date`. Omit to compare across the whole property.
</ParamField>

<ResponseField name="periodA / periodB" type="object">
  `{ startDate, endDate, totals }`, where `totals` is `clicks`, `impressions`, `ctr`, `position`.
</ResponseField>

<ResponseField name="delta" type="object">
  Differences: `clicks` and `impressions` have `{ absolute, percent }`; `ctr` and `position` have `{ absolute }`. `percent` is `null` if the baseline was `0`.
</ResponseField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "compare_periods",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "periodAStart": "2026-04-01",
      "periodAEnd": "2026-04-28",
      "periodBStart": "2026-05-01",
      "periodBEnd": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "dimension": null,
    "periodA": { "startDate": "2026-04-01", "endDate": "2026-04-28", "totals": { "clicks": 3800, "impressions": 81000, "ctr": 0.047, "position": 8.1 } },
    "periodB": { "startDate": "2026-05-01", "endDate": "2026-05-28", "totals": { "clicks": 4200, "impressions": 86000, "ctr": 0.049, "position": 7.6 } },
    "delta": {
      "clicks": { "absolute": 400, "percent": 10.5 },
      "impressions": { "absolute": 5000, "percent": 6.2 },
      "ctr": { "absolute": 0.002 },
      "position": { "absolute": -0.5 }
    }
  }
  ```
</CodeGroup>

***

## search\_analytics\_query

Advanced: send a raw Search Analytics query straight through to the Search Console API. For power users who want the full surface (dimensions, filters, pagination).

<ParamField path="requestBody" type="object" required>
  Raw Search Analytics request body:

  <Expandable title="fields" />
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__top_queries",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28",
      "limit": 5
    }
  }
  ```

  ```json Request theme={null}
  {
    "name": "search_analytics_query",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "requestBody": {
        "startDate": "2026-05-01",
        "endDate": "2026-05-28",
        "dimensions": ["query", "device"],
        "dimensionFilterGroups": [
          { "filters": [{ "dimension": "country", "operator": "equals", "expression": "dnk" }] }
        ],
        "rowLimit": 100,
        "dataState": "final"
      }
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "responseAggregationType": "byProperty",
    "rows": [
      { "keys": ["example keyword", "MOBILE"], "clicks": 210, "impressions": 5400, "ctr": 0.039, "position": 8.2 }
    ]
  }
  ```
</CodeGroup>

<Note>
  Fields like `ctr` (0–1) and `position` follow the Search Console API's own definitions. See [Errors & limits](/developers/errors-and-limits) for limits and data freshness.
</Note>

The most-clicked pages for a property over a date range. Same arguments as [`top_queries`](#top_queries) (`limit` defaults to `10`, max `25000`).

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__top_pages",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "pages": [
      { "page": "https://example.com/", "clicks": 980, "impressions": 21340, "ctr": 0.046, "position": 5.1 }
    ]
  }
  ```
</CodeGroup>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__query_performance",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "query": "example keyword",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "query": "example keyword",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "metrics": { "clicks": 421, "impressions": 9120, "ctr": 0.046, "position": 7.8 }
  }
  ```
</CodeGroup>

Like [`query_performance`](#query_performance), but for **a single page**. Use `page` (exact page URL) instead of `query`. Returns zeros if the page has no data in the period.

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__page_performance",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "page": "https://example.com/product",
      "startDate": "2026-05-01",
      "endDate": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "page": "https://example.com/product",
    "startDate": "2026-05-01",
    "endDate": "2026-05-28",
    "metrics": { "clicks": 132, "impressions": 4010, "ctr": 0.033, "position": 9.4 }
  }
  ```
</CodeGroup>

Compares Search Analytics metrics between **two periods** with both absolute and percentage differences. Can be broken down by a dimension. Totals are summed across the rows: `position` is the **impression-weighted average** and `ctr` is `clicks / impressions`.

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__compare_periods",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "periodAStart": "2026-04-01",
      "periodAEnd": "2026-04-28",
      "periodBStart": "2026-05-01",
      "periodBEnd": "2026-05-28"
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "dimension": null,
    "periodA": { "startDate": "2026-04-01", "endDate": "2026-04-28", "totals": { "clicks": 3800, "impressions": 81000, "ctr": 0.047, "position": 8.1 } },
    "periodB": { "startDate": "2026-05-01", "endDate": "2026-05-28", "totals": { "clicks": 4200, "impressions": 86000, "ctr": 0.049, "position": 7.6 } },
    "delta": {
      "clicks": { "absolute": 400, "percent": 10.5 },
      "impressions": { "absolute": 5000, "percent": 6.2 },
      "ctr": { "absolute": 0.002 },
      "position": { "absolute": -0.5 }
    }
  }
  ```
</CodeGroup>

<ParamField path="requestBody" type="object" required>
  Raw Search Analytics request body:

  <Expandable title="fields">
    <ResponseField name="startDate" type="string (YYYY-MM-DD)" required />

    <ResponseField name="endDate" type="string (YYYY-MM-DD)" required />
  </Expandable>
</ParamField>

<CodeGroup>
  ```json Request theme={null}
  {
    "name": "gsc__search_analytics_query",
    "arguments": {
      "siteUrl": "sc-domain:example.com",
      "requestBody": {
        "startDate": "2026-05-01",
        "endDate": "2026-05-28",
        "dimensions": ["query", "device"],
        "dimensionFilterGroups": [
          { "filters": [{ "dimension": "country", "operator": "equals", "expression": "dnk" }] }
        ],
        "rowLimit": 100,
        "dataState": "final"
      }
    }
  }
  ```

  ```json Result (payload) theme={null}
  {
    "siteUrl": "sc-domain:example.com",
    "responseAggregationType": "byProperty",
    "rows": [
      { "keys": ["example keyword", "MOBILE"], "clicks": 210, "impressions": 5400, "ctr": 0.039, "position": 8.2 }
    ]
  }
  ```
</CodeGroup>

<Note>
  Fields like `ctr` (0 to 1) and `position` follow the Search Console API's own definitions. See [Errors & limits](/developers/errors-and-limits) for limits and data freshness.
</Note>