Search Console: Compare Periods
gsc_compare_periodsCompare two Google Search Console periods by query, page, country or device to find top gainers and losers, new and lost keys, and period totals in one call instead of diffing queries manually.
Instructions
What changed between two periods, by one dimension: the top gainers and losers present in both, keys that are new or lost, and each period's returned_totals. This is the tool for "what dropped?" or "which pages grew?" — prefer it over two gsc_query_search_analytics calls and diffing them by eye. Defaults: current = the 28 days ending 3 days ago (Pacific), previous = the same-length window just before it. Runs two queries of depth rows each (1,000 by default); by query or page that is the expensive kind of load quota, so do not loop it. returned_totals sum the fetched rows only, not the property: rows past depth are not counted, and by query anonymized queries are missing. When a period fills depth, truncated is set and some new/lost keys may only have crossed the cut.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"site": "<site>",
"dimension": "<dimension>"
},
"name": "gsc_compare_periods"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | The Search Console property, e.g. "sc-domain:example.com" (a domain property: every protocol and subdomain) or "https://www.example.com/" (a URL-prefix property: exactly that scheme, host and path). A bare "example.com" or a URL without its trailing slash is resolved against the properties this account can see, preferring the domain property; the response's `site` says which property was read. gsc_list_sites lists them. | |
| type | No | Which Google surface: web (default, Search's main results), image, video, news (the News tab in Search), discover, googleNews (news.google.com and the News app), webMultimodal (Lens, Circle to Search, image uploads). discover and googleNews have no query dimension and no position. | web |
| depth | No | Rows fetched per period (1-5000), top keys by clicks. Defaults to 1000. Deeper finds smaller movers and fewer false new/lost keys, but grouping by query or page is what spends the 10-minute and daily load quotas, and the cost grows with the rows asked for — twice over, since both periods are queried. Raise it only when `truncated` is set and the tail matters. | |
| limit | No | How many gainers, losers, new and lost keys to return, each. Defaults to 25. | |
| metric | No | What to rank gainers and losers by. Defaults to clicks. For position lower is better, so a gainer's change is negative. | clicks |
| current | No | The period to explain. Defaults to the 28 days ending 3 days ago (Pacific). | |
| filters | No | Filters, all AND-ed together, e.g. [{"dimension":"page","operator":"contains","expression":"/blog/"}]. Filtering by page or query costs as much load quota as grouping by it. | |
| previous | No | The baseline. Defaults to the same number of days immediately before `current`; with only one bound given, the other is set so it is as long as `current`. Must not overlap it. Pass the same dates a year earlier for a year-over-year view. | |
| dimension | Yes | The one dimension to compare by, e.g. page for "which pages lost traffic". |