Google Search Console Abilities

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 or the authentication methods in the Abilities API overview. 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:

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
Method: GET

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
Method: GET

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 to update it from Google.

Get Site Mapping

Ability: mainwp/get-site-google-search-console-mapping-v1
Method: GET

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:

{
  "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
Method: DELETE Preview assigning a property returned by List Properties:

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. 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
Method: GET

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.

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.

Get Refresh Policy

Ability: mainwp/get-google-search-console-refresh-policy-v1
Method: GET

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:

{
  "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
Method: DELETE

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. 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
Method: POST

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:

{
  "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. After success, read the site observation again.

Request a Catalog Refresh

Ability: mainwp/request-google-search-console-catalog-refresh-v1
Method: POST

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. 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
Method: GET

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.

Google Search Console Add-on - Connect accounts and use the Dashboard interface
Abilities API Overview - Authentication, discovery, and HTTP methods
Cache Control Abilities - Cache status and purge automation

Getting Started

Understanding MainWP

Dashboard

Sites

Users

Updates

Plugins

Themes

Content Operations

Clients

MCP Server

API Reference

Troubleshooting

Customization

Advanced

Resources

What You’ll Learn

Prerequisites

Available Abilities

Inputs, Revisions, and Confirmation

List Connections

List Properties

Get Site Mapping

Replace Site Mapping

Get Cached Site Observation

Get Refresh Policy

Replace Refresh Policy

Request a Site Refresh

Request a Catalog Refresh

Get Refresh Status

Handling Errors

​What You’ll Learn

​Prerequisites

​Available Abilities

​Inputs, Revisions, and Confirmation

​List Connections

​List Properties

​Get Site Mapping

​Replace Site Mapping

​Get Cached Site Observation

​Get Refresh Policy

​Replace Refresh Policy

​Request a Site Refresh

​Request a Catalog Refresh

​Get Refresh Status

​Handling Errors

​Related Resources

What You’ll Learn

Prerequisites

Available Abilities

Inputs, Revisions, and Confirmation

List Connections

List Properties

Get Site Mapping

Replace Site Mapping

Get Cached Site Observation

Get Refresh Policy

Replace Refresh Policy

Request a Site Refresh

Request a Catalog Refresh

Get Refresh Status

Handling Errors

Related Resources