Tool reference
Find decaying pages or queries
Pages or queries in *sustained* decline across several whole periods - not a window-over-window drop, which cannot tell a decline from a bad month.
Tool name: find_content_decay
Cost: Free - not billed, and does not draw on a plan quota.
Read-only
This tool only reads. It never creates or changes anything, so an assistant may call it without asking you first.
Pages or queries in sustained decline across several whole periods - not a window-over-window drop, which cannot tell a decline from a bad month. Two shapes are reported and they imply different investigations: sustained is still falling period on period, and stepped is one drop that has held since, which is what a lost ranking, a redirect or a de-indexed page looks like (its decliningPeriods is 0 - flat at the lower level). changepoint gives the period the level changed and the two levels either side of it. Read the two engines' series differently: a Google period with no row arrives as 0, a Bing one arrives as null, because Bing's feeds are top-N cursors and an absence there is not a fall. That Google zero is what the row ceiling undermines: on a truncated period it is a missing row, not a measured zero, and a run of them reads as exactly the decline this tool looks for. Google stores only about 5,000 rows per day per single-dimension breakdown once a day is more than roughly three days old, so on a large site these rows are a top-N by impressions rather than a complete list. When that applies to the window you asked for, the response says so in unsupportedInputs with the dates - there is nothing to fetch, so read a missing row as 'not in the top ~5,000', never as 'zero'.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
site | string | Yes | The site to look up, as a bare domain ("example.com") or a URL - scheme, www., path and trailing slash are all stripped. Must resolve to a workspace the caller owns; call list_sites first if unsure of the exact domain. |
by | "query" | "page" | No | Decay pages (the usual question) or queries. Defaults to "page". |
granularity | "weekly" | "monthly" | No | Length of one period in the series. Daily is deliberately not offered: these tools ask whether a change was sustained across periods, and a one-day period turns that into weekday seasonality. Defaults to "monthly". |
periods | integer | No | How many whole periods to read. The period containing the anchor date is excluded when it is still running - see periodWindow.excludedPartialPeriod. Defaults to 6. |
to | string | No | Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for. |
minImpressions | integer | No | Minimum impressions over the whole window for an entity to be read at all. A floor on the range, not on each period - a per-period floor would delete the quiet periods a decline ends in. Defaults to 50. |
minDecliningPeriods | integer | No | Consecutive falling periods required for sustained. Defaults to 3. |
limit | integer | No | Maximum rows to return, sorted by relevance. Defaults to 50. |
searchVertical | "web" | "image" | "video" | No | Which Google search vertical to read: web (default), image, or video. Google-only - Bing Webmaster Tools does not split verticals on any traffic endpoint, so anything other than 'web' returns Google alone, with Bing excluded and declared in unsupportedInputs. A null or absent Bing figure then means 'not measurable', never 'zero'. Defaults to "web". |
Full input JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"site": {
"type": "string",
"minLength": 1,
"description": "The site to look up, as a bare domain (\"example.com\") or a URL - scheme, www., path and trailing slash are all stripped. Must resolve to a workspace the caller owns; call list_sites first if unsure of the exact domain."
},
"by": {
"default": "page",
"description": "Decay pages (the usual question) or queries.",
"type": "string",
"enum": ["query", "page"]
},
"granularity": {
"default": "monthly",
"description": "Length of one period in the series. Daily is deliberately not offered: these tools ask whether a change was sustained across periods, and a one-day period turns that into weekday seasonality.",
"type": "string",
"enum": ["weekly", "monthly"]
},
"periods": {
"default": 6,
"type": "integer",
"minimum": 2,
"maximum": 104,
"description": "How many whole periods to read. The period containing the anchor date is excluded when it is still running - see periodWindow.excludedPartialPeriod."
},
"to": {
"description": "Last day of the current window (YYYY-MM-DD). Defaults to the most recent date either engine has data for.",
"type": "string"
},
"minImpressions": {
"default": 50,
"description": "Minimum impressions over the whole window for an entity to be read at all. A floor on the range, not on each period - a per-period floor would delete the quiet periods a decline ends in.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"minDecliningPeriods": {
"default": 3,
"description": "Consecutive falling periods required for `sustained`.",
"type": "integer",
"minimum": 2,
"maximum": 12
},
"limit": {
"default": 50,
"description": "Maximum rows to return, sorted by relevance.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 500
},
"searchVertical": {
"default": "web",
"description": "Which Google search vertical to read: web (default), image, or video. Google-only - Bing Webmaster Tools does not split verticals on any traffic endpoint, so anything other than 'web' returns Google alone, with Bing excluded and declared in `unsupportedInputs`. A null or absent Bing figure then means 'not measurable', never 'zero'.",
"type": "string",
"enum": ["web", "image", "video"]
}
},
"required": ["site"]
}Response
Full output JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"site": {
"type": "string"
},
"workspaceId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"searchVertical": {
"type": "string",
"enum": ["web", "image", "video"]
},
"by": {
"type": "string"
},
"periodWindow": {
"type": "object",
"properties": {
"granularity": {
"type": "string"
},
"periods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"window": {
"type": "object",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
},
"required": ["start", "end"],
"additionalProperties": false
},
"periodStarts": {
"type": "array",
"items": {
"type": "string"
}
},
"excludedPartialPeriod": {
"anyOf": [
{
"type": "object",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
},
"required": ["start", "end"],
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"granularity",
"periods",
"window",
"periodStarts",
"excludedPartialPeriod"
],
"additionalProperties": {}
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"google": {
"anyOf": [
{
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"metric": {
"type": "string"
},
"decliningPeriods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dropFromPeak": {
"type": "number"
},
"estimatedClicksLost": {
"type": "number"
},
"changepoint": {
"anyOf": [
{
"type": "object",
"properties": {
"periodStart": {
"type": "string"
},
"before": {
"type": "object",
"properties": {
"periods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"clicksPerPeriod": {
"type": "number"
},
"impressionsPerPeriod": {
"type": "number"
}
},
"required": [
"periods",
"clicks",
"impressions",
"position",
"ctr",
"clicksPerPeriod",
"impressionsPerPeriod"
],
"additionalProperties": {}
},
"after": {
"type": "object",
"properties": {
"periods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"clicksPerPeriod": {
"type": "number"
},
"impressionsPerPeriod": {
"type": "number"
}
},
"required": [
"periods",
"clicks",
"impressions",
"position",
"ctr",
"clicksPerPeriod",
"impressionsPerPeriod"
],
"additionalProperties": {}
}
},
"required": [
"periodStart",
"before",
"after"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"periodStart": {
"type": "string"
},
"clicks": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"impressions": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"periodStart",
"clicks",
"impressions",
"position"
],
"additionalProperties": {}
}
}
},
"required": [
"pattern",
"metric",
"decliningPeriods",
"dropFromPeak",
"estimatedClicksLost",
"changepoint",
"series"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"bing": {
"anyOf": [
{
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"metric": {
"type": "string"
},
"decliningPeriods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"dropFromPeak": {
"type": "number"
},
"estimatedClicksLost": {
"type": "number"
},
"changepoint": {
"anyOf": [
{
"type": "object",
"properties": {
"periodStart": {
"type": "string"
},
"before": {
"type": "object",
"properties": {
"periods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"clicksPerPeriod": {
"type": "number"
},
"impressionsPerPeriod": {
"type": "number"
}
},
"required": [
"periods",
"clicks",
"impressions",
"position",
"ctr",
"clicksPerPeriod",
"impressionsPerPeriod"
],
"additionalProperties": {}
},
"after": {
"type": "object",
"properties": {
"periods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"clicksPerPeriod": {
"type": "number"
},
"impressionsPerPeriod": {
"type": "number"
}
},
"required": [
"periods",
"clicks",
"impressions",
"position",
"ctr",
"clicksPerPeriod",
"impressionsPerPeriod"
],
"additionalProperties": {}
}
},
"required": [
"periodStart",
"before",
"after"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"periodStart": {
"type": "string"
},
"clicks": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"impressions": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
}
},
"required": [
"periodStart",
"clicks",
"impressions",
"position"
],
"additionalProperties": {}
}
}
},
"required": [
"pattern",
"metric",
"decliningPeriods",
"dropFromPeak",
"estimatedClicksLost",
"changepoint",
"series"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"totalEstimatedClicksLost": {
"type": "number"
}
},
"required": [
"label",
"google",
"bing",
"totalEstimatedClicksLost"
],
"additionalProperties": {}
}
},
"unsupportedInputs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"engine": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"reason": {
"type": "string"
}
},
"required": ["field", "reason"],
"additionalProperties": {}
}
},
"lastSyncedAt": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"site",
"workspaceId",
"searchVertical",
"by",
"periodWindow",
"rows",
"unsupportedInputs"
],
"additionalProperties": false
}