# Google Search Console

Google Search Console reports how a site performs in Google Search: which queries show it, which pages get clicks, and whether Google can crawl and index each URL. One API for Agents calls the Search Console API on your behalf with read-only access.

- Provider id: `gsc`
- Auth: Sign in with Google (OAuth), Service account
- Google scopes: `https://www.googleapis.com/auth/webmasters.readonly`
- Raw endpoints: 6. Smart tools: 2.
- Machine-readable schemas: `GET https://api.oneapiforagents.com/v1/providers/gsc`

## Smart tools

Curated calls with compact output for agents. Over MCP each one is a tool with the same name.

### gsc_top_queries

Top search queries by clicks for a property over the last N days.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–480) |
| `limit` | integer | no | Maximum rows to return Default `25`. (1–1000) |
| `page` | string (uri) | no | Only queries that led to this page |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsc",
    "tool": "gsc_top_queries",
    "input": {
      "siteUrl": "sc-domain:example.com",
      "days": 28,
      "limit": 10
    }
  }'
```

### gsc_quick_wins

Queries ranking just off page one (default positions 8–20) with meaningful impressions, sorted by impressions.

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `siteUrl` | string | yes | Property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `days` | integer | no | How many days back from the latest available data Default `28`. (1–480) |
| `minImpressions` | integer | no | Default `100`. (≥ 0) |
| `minPosition` | number | no | Default `8`. (≥ 1) |
| `maxPosition` | number | no | Default `20`. (≥ 1) |
| `limit` | integer | no | Maximum rows to return Default `50`. (1–500) |

```sh
curl https://api.oneapiforagents.com/v1/call \
  -H "Authorization: Bearer $ONEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "gsc",
    "tool": "gsc_quick_wins",
    "input": {
      "siteUrl": "sc-domain:example.com",
      "days": 28
    }
  }'
```

## Raw endpoints

Passthrough to the provider API. `path` fills URL placeholders, `query` the query string and `body` the JSON body. The response is the provider's own body.

### sites.list

List Search Console properties this connection can read.

`GET https://www.googleapis.com/webmasters/v3/sites`

No input.

```json
{
  "provider": "gsc",
  "endpoint": "sites.list"
}
```

### sites.get

Get one property and the connection's permission level on it.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |

```json
{
  "provider": "gsc",
  "endpoint": "sites.get",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

### searchanalytics.query

Search Analytics: clicks, impressions, CTR and position grouped by dimensions.

`POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `body.startDate` | string (date) | yes | First day, YYYY-MM-DD |
| `body.endDate` | string (date) | yes | Last day, YYYY-MM-DD |
| `body.dimensions` | array<string> | no | Group rows by these dimensions One of: `date`, `query`, `page`, `country`, `device`, `searchAppearance`, `hour`. |
| `body.type` | string | no | One of: `web`, `image`, `video`, `news`, `discover`, `googleNews`. |
| `body.dimensionFilterGroups` | array<object> | no |  |
| `body.aggregationType` | string | no | One of: `auto`, `byPage`, `byProperty`, `byNewsShowcasePanel`. |
| `body.rowLimit` | integer | no | Maximum rows to return (1–25000) |
| `body.startRow` | integer | no | Zero-based row offset for paging (≥ 0) |
| `body.dataState` | string | no | One of: `final`, `all`, `hourly_all`. |

```json
{
  "provider": "gsc",
  "endpoint": "searchanalytics.query",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    },
    "body": {
      "startDate": "2026-08-01",
      "endDate": "2026-08-28",
      "dimensions": [
        "query"
      ],
      "rowLimit": 10
    }
  }
}
```

### sitemaps.list

List sitemaps submitted for a property.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `query.sitemapIndex` | string | no | Only sitemaps listed in this sitemap index |

```json
{
  "provider": "gsc",
  "endpoint": "sitemaps.list",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```

### sitemaps.get

Get one submitted sitemap.

`GET https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/sitemaps/{feedpath}`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `path.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `path.feedpath` | string | yes | Full sitemap URL |

```json
{
  "provider": "gsc",
  "endpoint": "sitemaps.get",
  "input": {
    "path": {
      "siteUrl": "sc-domain:example.com",
      "feedpath": "https://example.com/sitemap.xml"
    }
  }
}
```

### urlInspection.index.inspect

URL Inspection: index status, crawl and rich-result details for one URL.

`POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect`

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `body.inspectionUrl` | string (uri) | yes | Fully qualified URL to inspect, inside siteUrl |
| `body.siteUrl` | string | yes | Search Console property, e.g. "sc-domain:example.com" or "https://example.com/" |
| `body.languageCode` | string | no | Language for issue messages, e.g. "en-US" |

```json
{
  "provider": "gsc",
  "endpoint": "urlInspection.index.inspect",
  "input": {
    "body": {
      "inspectionUrl": "https://example.com/pricing",
      "siteUrl": "sc-domain:example.com"
    }
  }
}
```