Search Console API and MCP tools

search_console_summary

GET /api/v1/sites/{site}/search-console/summary

Clicks, impressions, CTR and average position for a period, the previous period and the daily series. Served from synced data; with a range of 3 months or more, from/to, compare, search_type or filters it is a live Search Console query (cached for an hour).

MCP tool search_console_summary Scope read:seo Plan Pro and above

Parameters

Name	In	Type	Required	Description
`site`	path	`string`	Yes	Host of one of your sites, e.g. example.com (see list_sites).
`range`	query	`string`	No	Period ending yesterday. Default 28d. 3m and longer are live from Google. One of: 7d, 28d, 90d, 3m, 6m, 12m, 16m.
`from`	query	`string`	No	With to: a custom date range (YYYY-MM-DD), up to 16 months back. Answered live from Google (cached for an hour).
`to`	query	`string`	No	End of the custom date range (YYYY-MM-DD), not in the future.
`compare`	query	`string`	No	Compare with the previous period of the same length, or the same dates a year earlier (live). One of: none, previous, year.
`search_type`	query	`string`	No	Search Console search type (live). Default web. One of: web, image, video, news, discover, googleNews.
`filters`	query	`array<object>`	No	Up to 8 conditions, all must match (live): a list of {"dimension": query\|page\|country\|device\|appearance, "operator": "contains\|not_contains\|equals\|not_equals\|regex\|not_regex", "value"}. Regular expressions use RE2 syntax. In Search Console country is a 3-letter code (deu) and device is desktop, mobile or tablet.

Example request

bash

curl "https://woodander.com/api/v1/sites/example.com/search-console/summary" \
  -H "Authorization: Bearer wdr_..."

tools/call

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_console_summary",
        "arguments": {
            "site": "example.com"
        }
    }
}

Example response Example

json

{
    "data": {
        "site": "example.com",
        "property": "sc-domain:example.com",
        "range": {
            "key": "28d",
            "days": 28,
            "from": "2026-09-18",
            "to": "2026-10-15"
        },
        "totals": {
            "clicks": 420,
            "impressions": 9800,
            "ctr": 4.29,
            "position": 11.4
        },
        "previous_period": {
            "clicks": 380,
            "impressions": 9100,
            "ctr": 4.18,
            "position": 12
        },
        "daily": [
            {
                "date": "2026-10-15",
                "clicks": 15,
                "impressions": 350,
                "ctr": 4.29,
                "position": 11.1
            }
        ]
    },
    "meta": {
        "synced_at": "2026-10-17T03:00:00+00:00",
        "source": "synced_search_console"
    }
}

Errors

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the read:seo scope.
403	`plan_required`	The plan does not include API access.
404	`not_found`	Not found, or not yours.
422	`invalid_request`	A parameter is not valid (range, type, cursor).
404	`search_console_not_connected`	The site has no connected Search Console property.
429	`rate_limited`	Too many requests. See the Retry-After header.

search_console_queries

GET /api/v1/sites/{site}/search-console/queries

Search queries of the last 28 days (the synced snapshot), sortable and filterable. With from/to, range, compare, search_type, dimension or filters it is a live Search Console query (up to 25,000 rows, cached for an hour).

MCP tool search_console_queries Scope read:seo Plan Pro and above

Parameters

Name	In	Type	Required	Description
`site`	path	`string`	Yes	Host of one of your sites, e.g. example.com (see list_sites).
`range`	query	`string`	No	Period ending yesterday. Default 28d. 3m and longer are live from Google. One of: 7d, 28d, 3m, 6m, 12m, 16m.
`from`	query	`string`	No	With to: a custom date range (YYYY-MM-DD), up to 16 months back. Answered live from Google (cached for an hour).
`to`	query	`string`	No	End of the custom date range (YYYY-MM-DD), not in the future.
`compare`	query	`string`	No	Compare with the previous period of the same length, or the same dates a year earlier (live). One of: none, previous, year.
`search_type`	query	`string`	No	Search Console search type (live). Default web. One of: web, image, video, news, discover, googleNews.
`dimension`	query	`string`	No	Group the rows by this dimension instead of the default (live). One of: query, page, country, device, date, appearance.
`filters`	query	`array<object>`	No	Up to 8 conditions, all must match (live): a list of {"dimension": query\|page\|country\|device\|appearance, "operator": "contains\|not_contains\|equals\|not_equals\|regex\|not_regex", "value"}. Regular expressions use RE2 syntax. In Search Console country is a 3-letter code (deu) and device is desktop, mobile or tablet.
`filter`	query	`string`	No	Keep queries containing this text.
`sort`	query	`string`	No	Default clicks. Position sorts best first. One of: clicks, impressions, ctr, position.
`limit`	query	`integer`	No	Page size, 1 to 200.
`cursor`	query	`string`	No	meta.next_cursor of the previous page.

Example request

bash

curl "https://woodander.com/api/v1/sites/example.com/search-console/queries" \
  -H "Authorization: Bearer wdr_..."

tools/call

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_console_queries",
        "arguments": {
            "site": "example.com"
        }
    }
}

Example response Example

json

{
    "data": [
        {
            "value": "best seo tools",
            "clicks": 12,
            "impressions": 340,
            "ctr": 3.53,
            "position": 6.2
        }
    ],
    "meta": {
        "next_cursor": null,
        "limit": 50,
        "total": 1,
        "site": "example.com",
        "dimension": "query",
        "window": "last_28_days",
        "sort": "clicks",
        "synced_at": "2026-10-17T03:00:00+00:00"
    }
}

Errors

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the read:seo scope.
403	`plan_required`	The plan does not include API access.
404	`not_found`	Not found, or not yours.
422	`invalid_request`	A parameter is not valid (range, type, cursor).
404	`search_console_not_connected`	The site has no connected Search Console property.
429	`rate_limited`	Too many requests. See the Retry-After header.

search_console_pages

GET /api/v1/sites/{site}/search-console/pages

Pages of the last 28 days (the synced snapshot), sortable and filterable. With from/to, range, compare, search_type, dimension or filters it is a live Search Console query (up to 25,000 rows, cached for an hour).

MCP tool search_console_pages Scope read:seo Plan Pro and above

Parameters

Name	In	Type	Required	Description
`site`	path	`string`	Yes	Host of one of your sites, e.g. example.com (see list_sites).
`range`	query	`string`	No	Period ending yesterday. Default 28d. 3m and longer are live from Google. One of: 7d, 28d, 3m, 6m, 12m, 16m.
`from`	query	`string`	No	With to: a custom date range (YYYY-MM-DD), up to 16 months back. Answered live from Google (cached for an hour).
`to`	query	`string`	No	End of the custom date range (YYYY-MM-DD), not in the future.
`compare`	query	`string`	No	Compare with the previous period of the same length, or the same dates a year earlier (live). One of: none, previous, year.
`search_type`	query	`string`	No	Search Console search type (live). Default web. One of: web, image, video, news, discover, googleNews.
`dimension`	query	`string`	No	Group the rows by this dimension instead of the default (live). One of: query, page, country, device, date, appearance.
`filters`	query	`array<object>`	No	Up to 8 conditions, all must match (live): a list of {"dimension": query\|page\|country\|device\|appearance, "operator": "contains\|not_contains\|equals\|not_equals\|regex\|not_regex", "value"}. Regular expressions use RE2 syntax. In Search Console country is a 3-letter code (deu) and device is desktop, mobile or tablet.
`filter`	query	`string`	No	Keep page URLs containing this text.
`sort`	query	`string`	No	Default clicks. Position sorts best first. One of: clicks, impressions, ctr, position.
`limit`	query	`integer`	No	Page size, 1 to 200.
`cursor`	query	`string`	No	meta.next_cursor of the previous page.

Example request

bash

curl "https://woodander.com/api/v1/sites/example.com/search-console/pages" \
  -H "Authorization: Bearer wdr_..."

tools/call

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_console_pages",
        "arguments": {
            "site": "example.com"
        }
    }
}

Example response Example

json

{
    "data": [
        {
            "value": "https://example.com/blog/guide",
            "clicks": 12,
            "impressions": 340,
            "ctr": 3.53,
            "position": 6.2
        }
    ],
    "meta": {
        "next_cursor": null,
        "limit": 50,
        "total": 1,
        "site": "example.com",
        "dimension": "page",
        "window": "last_28_days",
        "sort": "clicks",
        "synced_at": "2026-10-17T03:00:00+00:00"
    }
}

Errors

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the read:seo scope.
403	`plan_required`	The plan does not include API access.
404	`not_found`	Not found, or not yours.
422	`invalid_request`	A parameter is not valid (range, type, cursor).
404	`search_console_not_connected`	The site has no connected Search Console property.
429	`rate_limited`	Too many requests. See the Retry-After header.

search_opportunities

GET /api/v1/sites/{site}/search-console/opportunities

Queries worth acting on: striking distance (position 4 to 20) and low click-through in the top 5.

MCP tool search_opportunities Scope read:seo Plan Pro and above

Parameters

Name	In	Type	Required	Description
`site`	path	`string`	Yes	Host of one of your sites, e.g. example.com (see list_sites).

Example request

bash

curl "https://woodander.com/api/v1/sites/example.com/search-console/opportunities" \
  -H "Authorization: Bearer wdr_..."

tools/call

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_opportunities",
        "arguments": {
            "site": "example.com"
        }
    }
}

Example response Example

json

{
    "data": {
        "site": "example.com",
        "striking_distance": [
            {
                "value": "best seo tools",
                "clicks": 12,
                "impressions": 340,
                "ctr": 3.53,
                "position": 6.2
            }
        ],
        "low_ctr": []
    },
    "meta": {
        "window": "last_28_days",
        "synced_at": "2026-10-17T03:00:00+00:00"
    }
}

Errors

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the read:seo scope.
403	`plan_required`	The plan does not include API access.
404	`not_found`	Not found, or not yours.
404	`search_console_not_connected`	The site has no connected Search Console property.
429	`rate_limited`	Too many requests. See the Retry-After header.

queue_search_console_sync

POST /api/v1/sites/{site}/search-console/sync

Queue a refresh of the stored Search Console figures of one of your sites (never a live Google call from this request). Refused while the figures are under 15 minutes old. What happens depends on the mode the owner set for this module in Settings → AI activity: Manual stores a proposal the owner applies in the Workspace (the answer has a confirm_url), Hybrid and Autonomous run it. Poll agent_change_status with the id.

MCP tool queue_search_console_sync Scope run:audits Plan Pro and above

Parameters

Name	In	Type	Required	Description
`site`	path	`string`	Yes	Host of one of your sites (see list_sites).

Example request

bash

curl -X POST "https://woodander.com/api/v1/sites/example.com/search-console/sync" \
  -H "Authorization: Bearer wdr_..."

tools/call

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "queue_search_console_sync",
        "arguments": {
            "site": "example.com"
        }
    }
}

Example response Example

json

{
    "data": {
        "id": 41,
        "action": "seo.queue_search_console_sync",
        "risk": "reversible",
        "status": "done",
        "needs": null,
        "summary": "Refresh the Search Console figures of example.com",
        "diff": [],
        "requested_by": "Token “Claude Code”",
        "note": null,
        "error": null,
        "result": {
            "summary": "Search Console refresh of example.com queued."
        },
        "confirm_url": null,
        "created_at": "2026-10-19T09:00:00+00:00",
        "decided_at": null
    },
    "meta": {
        "outcome": "done",
        "module": "seo",
        "mode": "hybrid",
        "hint": null
    }
}

Errors

HTTP	Code	Meaning
401	`unauthenticated`	Missing, invalid, expired or revoked token.
403	`insufficient_scope`	The token does not have the run:audits scope.
403	`plan_required`	The plan does not include API access.
404	`not_found`	Not found, or not yours.
404	`search_console_not_connected`	The site has no connected Search Console property.
429	`rate_limited`	Too many requests. See the Retry-After header.