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

# Google Search Console Abilities

> Inspect Google Search Console connections, manage site mappings and refresh settings, read cached metrics, and track background refreshes with the MainWP Abilities API.

MainWP Google Search Console 6.3 registers ten abilities in the `mainwp-google-search-console` category. All use the `mainwp/` namespace on your MainWP Dashboard and are available to MainWP AI Assistant and authenticated API clients.

## What You'll Learn

* List connections and exact property scopes
* Read or replace a site's property mapping
* Read cached aggregate search performance
* Inspect and change refresh settings
* Request background refreshes and check their outcomes

## Prerequisites

* WordPress 6.9 or later on the MainWP Dashboard site
* MainWP Dashboard with Abilities API support; use version 6.2 or later for the `input_json` and DELETE request examples below
* Google Search Console 6.3 or later, active on MainWP Dashboard
* An authenticated WordPress user with `manage_options` and access to the Google Search Console Add-on
* A configured Google connection for property mappings and refreshes

Use an [Application Password](/api-reference/rest-api/application-passwords) or the [authentication methods in the Abilities API overview](/api-reference/abilities-api/overview#authentication). The examples use an Application Password.

Site-specific abilities also require `edit_sites`, access to the selected site, and a connected Child site. Team Control restrictions apply. Connection and property lists are administrator-level catalog views; their mapped-site counts respect site access. Refresh-status reads require Add-on access and either ownership of the job or administrator permission.

## Available Abilities

| Ability                                                   | Method | Purpose                                          |
| --------------------------------------------------------- | ------ | ------------------------------------------------ |
| `mainwp/list-google-search-console-connections-v1`        | GET    | List stored connection health                    |
| `mainwp/list-google-search-console-properties-v1`         | GET    | List cached properties and their exact scopes    |
| `mainwp/get-site-google-search-console-mapping-v1`        | GET    | Read a site's mapping and cache state            |
| `mainwp/replace-site-google-search-console-mapping-v1`    | DELETE | Preview or replace a mapping, including removal  |
| `mainwp/get-site-google-search-console-observation-v1`    | GET    | Read cached aggregate performance                |
| `mainwp/get-google-search-console-refresh-policy-v1`      | GET    | Read refresh settings and scheduler state        |
| `mainwp/replace-google-search-console-refresh-policy-v1`  | DELETE | Preview or replace refresh settings              |
| `mainwp/request-site-google-search-console-refresh-v1`    | POST   | Queue a site observation refresh                 |
| `mainwp/request-google-search-console-catalog-refresh-v1` | POST   | Preview or queue a connection's property refresh |
| `mainwp/get-google-search-console-refresh-status-v1`      | GET    | Read an ability-requested refresh job            |

Discover the abilities and their complete input and output schemas:

```bash theme={null}
curl -u 'USERNAME:APPLICATION_PASSWORD' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?category=mainwp-google-search-console'
```

The two replacement abilities use **DELETE**, including for previews, because the Abilities API routes destructive, idempotent abilities to that method. They change MainWP settings and cached data; they do not delete properties from Google Search Console.

## Inputs, Revisions, and Confirmation

Site calls use `site_id_or_domain`, which accepts a site ID or domain. The examples use site ID `1`. These abilities reject unknown input fields.

Connection references, property references, and revisions are opaque 64-character hexadecimal strings. Read them from the API rather than constructing them from a domain or Google account. The repeated `a` and `b` values below are fictional examples: replace them with the relevant returned reference or revision. Replace example UUIDs with a new UUID for each logical request.

For changes and refresh requests, `if_match` is an input field containing the current revision of the resource being changed:

| Operation                                   | Read the revision from |
| ------------------------------------------- | ---------------------- |
| Replace a mapping or request a site refresh | Get Site Mapping       |
| Replace refresh settings                    | Get Refresh Policy     |
| Request a connection catalog refresh        | List Connections       |

Mapping replacements, policy replacements, and catalog refreshes require exactly one of `dry_run` and `confirm` to be `true`. Start with `dry_run: true, confirm: false`, inspect the effects, then send the same request with `dry_run: false, confirm: true` to proceed. Keep the original `if_match` and `request_ref` for that preview-to-confirmation sequence. A site observation refresh has no preview or confirmation flags.

`request_ref` identifies one logical request. When retrying that exact request after a lost response, reuse its UUID and payload. If the target, revision, or requested settings change, use a new UUID. A stale revision requires reading the resource again and reviewing a new request; do not blindly retry with a newer revision.

***

## List Connections

**Ability:** `mainwp/list-google-search-console-connections-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"limit":50}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-google-search-console-connections-v1/run'
```

| Optional parameter     | Default | Description                                                                                              |
| ---------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `status`               | `null`  | Filter by `connected`, `needs_reauthorization`, `credential_unavailable`, `no_properties`, or `disabled` |
| `after_connection_ref` | `null`  | Cursor returned by the previous page                                                                     |
| `limit`                | `50`    | Page size from `1` to `100`                                                                              |

The response contains `connections`, `next_after_connection_ref`, and `truncated`. Each connection includes `connection_ref`, `label`, `method` (`oauth` or `service_account`), `status`, `property_count`, `mapped_site_count`, `last_catalog_refresh_at`, and `revision`.

While `truncated` is `true`, pass `next_after_connection_ref` as `after_connection_ref` to read the next page. Connection health comes from stored state; this call does not contact Google or return credentials.

## List Properties

**Ability:** `mainwp/list-google-search-console-properties-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"usable":true,"limit":50}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-google-search-console-properties-v1/run'
```

| Optional parameter   | Default | Description                                                 |
| -------------------- | ------- | ----------------------------------------------------------- |
| `connection_ref`     | `null`  | Limit results to one connection                             |
| `usable`             | `null`  | Filter by whether the cached property is usable for mapping |
| `after_property_ref` | `null`  | Cursor returned by the previous page                        |
| `limit`              | `50`    | Page size from `1` to `100`                                 |

The response contains `properties`, `next_after_property_ref`, and `truncated`. Each property includes `property_ref`, `connection_ref`, `property_type`, `property_scope`, `label`, `permission`, `usable`, `mapped_site_count`, and `revision`.

`property_type` is `domain` or `url_prefix`. The exact `property_scope` matters: `sc-domain:example.com` and `https://example.com/` are distinct properties. Select the returned `property_ref` for the intended scope. Permission values are `owner`, `full`, `restricted`, `unverified`, or `unknown`; usability also depends on the stored connection state.

While `truncated` is `true`, pass `next_after_property_ref` as `after_property_ref`. This reads the cached catalog. Use a [catalog refresh](#request-a-catalog-refresh) to update it from Google.

## Get Site Mapping

**Ability:** `mainwp/get-site-google-search-console-mapping-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"site_id_or_domain":1}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-site-google-search-console-mapping-v1/run'
```

**Example response for an unmapped site:**

```json theme={null}
{
  "site_id": 1,
  "status": "unmapped",
  "property_ref": null,
  "connection_ref": null,
  "property_type": null,
  "property_label": null,
  "cache_status": "none",
  "cache_generated_at": null,
  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```

`status` is `unmapped`, `mapped`, or `stale`. A stale mapping needs attention, for example after its property disappears from a refreshed catalog. `cache_status` is `none`, `fresh`, `stale`, or `malformed`. Use the returned mapping `revision` when replacing the mapping or requesting a site refresh.

## Replace Site Mapping

**Ability:** `mainwp/replace-site-google-search-console-mapping-v1`<br />
**Method:** DELETE

Preview assigning a property returned by List Properties:

```bash theme={null}
curl -X DELETE -u 'USERNAME:APPLICATION_PASSWORD' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"site_id_or_domain":1,"property_ref":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","if_match":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_ref":"11111111-1111-4111-8111-111111111111","dry_run":true,"confirm":false}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/replace-site-google-search-console-mapping-v1/run'
```

Required fields are `site_id_or_domain`, `property_ref`, `if_match`, and `request_ref`, plus the [confirmation flags](#inputs-revisions-and-confirmation). Set `property_ref` to `null` to remove the mapping. A non-null reference must identify a usable property.

The response includes `mode` (`preview` or `executed`), `request_id`, `site_id`, `would_change`, `changed`, `cache_would_invalidate`, `cache_invalidated`, and `mapping`. The nested mapping contains its status, property and connection references, property type and label, and revision.

The preview's nested mapping describes the proposed result. Keep the original revision from Get Site Mapping as `if_match` when confirming; do not substitute the proposed mapping's revision. Changing the mapping invalidates the site's cached Search Console data. This operation does not contact Google or fetch replacement statistics.

## Get Cached Site Observation

**Ability:** `mainwp/get-site-google-search-console-observation-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"site_id_or_domain":1,"include_daily":true}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-site-google-search-console-observation-v1/run'
```

`site_id_or_domain` is required. `include_daily` is optional and defaults to `false`.

The response includes `site_id`, `availability`, `period` (`week`, `month`, or `null`), `period_start`, `period_end`, `generated_at`, `stale`, `totals`, `daily`, and `revision`. Unavailable dates and metrics can be `null`.

| Availability | Meaning                                                                                    |
| ------------ | ------------------------------------------------------------------------------------------ |
| `unmapped`   | No property is assigned                                                                    |
| `no_cache`   | No validated aggregate observation is stored                                               |
| `available`  | A valid cached observation is available                                                    |
| `stale`      | The mapping or cached observation is stale; check the returned fields before using metrics |
| `malformed`  | Stored data could not be validated for this response                                       |

`totals` contains `clicks`, `impressions`, `click_through_rate`, `average_position`, `sitemap_submitted`, `sitemap_indexed`, `sitemap_errors`, and `indexing_rate`. Click-through rate is a fraction from `0` to `1`; indexing rate is a percentage from `0` to `100`.

When requested, `daily` contains up to 31 entries with `date`, `clicks`, `impressions`, `click_through_rate`, and `average_position`. Otherwise it is an empty array. Observations older than 48 hours are marked stale. A stale mapping can return no metrics at all.

<Note>
  This ability does not contact Google. It returns validated aggregate data, excluding search queries, individual page URLs, sitemap URLs, credentials, and raw Google responses. Older cached data visible in the Add-on may not yet have this aggregate representation. Request a site refresh when `availability` is `no_cache` and the mapping is valid.
</Note>

## Get Refresh Policy

**Ability:** `mainwp/get-google-search-console-refresh-policy-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-google-search-console-refresh-policy-v1/run'
```

**Example response:**

```json theme={null}
{
  "report_period": "month",
  "auto_refresh": true,
  "refresh_hours": 9,
  "scheduler_mode": "wordpress",
  "schedule_state": "scheduled",
  "last_refresh_at": "2026-09-23T06:00:00Z",
  "next_refresh_at": "2026-09-23T15:00:00Z",
  "revision": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
```

`scheduler_mode` is `wordpress`, `external`, or `disabled`. `schedule_state` is `scheduled`, `unscheduled`, or `drifted`; drift indicates a mismatch between the policy and the WordPress scheduled event. External scheduling can correctly report `unscheduled` with a null `next_refresh_at`.

`last_refresh_at` and `next_refresh_at` can be `null`. The last refresh time records a scheduled run with at least one successful refresh, not successful completion for every site. Use job status to check a particular ability-requested refresh.

## Replace Refresh Policy

**Ability:** `mainwp/replace-google-search-console-refresh-policy-v1`<br />
**Method:** DELETE

```bash theme={null}
curl -X DELETE -u 'USERNAME:APPLICATION_PASSWORD' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"report_period":"month","auto_refresh":true,"refresh_hours":9,"if_match":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_ref":"22222222-2222-4222-8222-222222222222","dry_run":true,"confirm":false}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/replace-google-search-console-refresh-policy-v1/run'
```

Supply all three settings, even when changing only one:

| Required setting | Allowed values                     |
| ---------------- | ---------------------------------- |
| `report_period`  | `week` or `month`                  |
| `auto_refresh`   | `true` or `false`                  |
| `refresh_hours`  | `1`, `3`, `9`, `15`, `18`, or `24` |

Also provide `if_match` from Get Refresh Policy, a `request_ref`, and the [confirmation flags](#inputs-revisions-and-confirmation).

The response includes `mode`, `request_id`, `would_change`, `changed`, `schedule_would_change`, `schedule_changed`, `caches_would_invalidate`, `caches_invalidated`, and `policy`. Cache fields are counts. The preview returns the current policy alongside the predicted effects; after execution, `policy` contains the resulting settings and scheduler state.

Policy changes can invalidate cached data across sites. Confirming also reconciles the schedule, including when settings stay the same but the schedule has drifted. It does not immediately fetch data from Google.

## Request a Site Refresh

**Ability:** `mainwp/request-site-google-search-console-refresh-v1`<br />
**Method:** POST

```bash theme={null}
curl -X POST -u 'USERNAME:APPLICATION_PASSWORD' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"site_id_or_domain":1,"if_match":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_ref":"33333333-3333-4333-8333-333333333333"}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/request-site-google-search-console-refresh-v1/run'
```

All three input fields are required. Use the revision from Get Site Mapping. This ability does not accept `dry_run` or `confirm`.

**Example response:**

```json theme={null}
{
  "job_id": "55555555-5555-4555-8555-555555555555",
  "request_id": "33333333-3333-4333-8333-333333333333",
  "kind": "site_observation",
  "site_id": 1,
  "status": "requested",
  "requested_at": "2026-09-23T09:00:00Z"
}
```

This queues a background job; `requested` does not mean new statistics are available. Save `job_id` and [check refresh status](#get-refresh-status). After success, read the site observation again.

## Request a Catalog Refresh

**Ability:** `mainwp/request-google-search-console-catalog-refresh-v1`<br />
**Method:** POST

```bash theme={null}
curl -X POST -u 'USERNAME:APPLICATION_PASSWORD' \
  -H 'Content-Type: application/json' \
  -d '{"input":{"connection_ref":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","if_match":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","request_ref":"44444444-4444-4444-8444-444444444444","dry_run":true,"confirm":false}}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/request-google-search-console-catalog-refresh-v1/run'
```

Provide `connection_ref`, that connection's current `revision` as `if_match`, a `request_ref`, and the [confirmation flags](#inputs-revisions-and-confirmation).

The response includes `mode` and `status` (`preview` or `requested`), `job_id`, `request_id`, `connection_ref`, `effects`, and `requested_at`. Preview responses have null `job_id` and `requested_at`.

`effects` contains `current_property_count`, `current_mapping_count`, `maximum_mapping_invalidations`, and `maximum_cache_invalidations`. A preview does not contact Google, so these are current counts and conservative impact limits, not a prediction of which properties Google will return.

After confirmation, the job refreshes that connection's property catalog. It can add, update, or remove local property entries, reconcile site mappings, and invalidate affected caches. A property that is no longer available can leave its mapping stale. This job does not delete properties from Google or replace a site observation refresh.

## Get Refresh Status

**Ability:** `mainwp/get-google-search-console-refresh-status-v1`<br />
**Method:** GET

```bash theme={null}
curl -G -u 'USERNAME:APPLICATION_PASSWORD' \
  --data-urlencode 'input_json={"job_ref":"55555555-5555-4555-8555-555555555555"}' \
  'https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-google-search-console-refresh-status-v1/run'
```

Pass the returned `job_id` as the required `job_ref`. This reads jobs requested through these abilities, not the history of ordinary scheduled or manual UI refreshes.

The response includes `job_id`, `kind` (`site_observation` or `connection_catalog`), `target`, `status`, `phase`, `attempts`, `result`, `requested_at`, `updated_at`, and `completed_at`. The target identifies a `site_id` or `connection_ref`; the unused field is `null`. `completed_at` is `null` until a terminal outcome is recorded.

| Status      | Interpretation                                                                                      |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `requested` | Queued, or waiting for another attempt                                                              |
| `running`   | Work is in progress                                                                                 |
| `succeeded` | The job completed successfully; inspect its result and read the updated resource                    |
| `failed`    | The job failed; inspect `result.code` before requesting more work                                   |
| `unknown`   | The final outcome could not be established; inspect current state before submitting another request |

`phase` is `queued`, `authorizing`, `preparing`, `provider_request`, `validating`, `committing`, or `complete`. Jobs use WordPress cron and can make up to three attempts for retryable failures. Authorization and resource revisions are checked again when work runs, so a queued job can fail if access or mappings change.

The result contains `properties_added`, `properties_updated`, `properties_removed`, `mappings_invalidated`, `caches_invalidated`, `cache_updated`, `revision`, and `code`. Use these fields to distinguish a catalog change from a site-cache update. Error codes can indicate problems such as `credential_unavailable`, `provider_auth`, `provider_quota`, `stale_revision`, `mapping_invalid`, or `outcome_unknown`.

## Handling Errors

Ability errors use the `mainwp_google_search_console_` prefix. Authentication and access errors require an authorized user; confirmation errors require the correct preview or confirmation flags. For a stale revision, read the current resource and review the intended change again. For credential or provider authorization failures, repair the connection through the Add-on before requesting another refresh.

A successful request to queue work is not proof that Google data was refreshed. Poll the returned job, inspect its terminal result, then read the updated mapping, catalog, or observation. If a job remains queued, check that WordPress cron is running on the MainWP Dashboard site.

## Related Resources

* [Google Search Console Add-on](/add-ons/analytics/google-search-console-extension) - Connect accounts and use the Dashboard interface
* [Abilities API Overview](/api-reference/abilities-api/overview) - Authentication, discovery, and HTTP methods
* [Cache Control Abilities](/api-reference/abilities-api/cache-control) - Cache status and purge automation