Tool reference
Find emerging keywords
Queries with sustained or accelerating growth over several whole periods - find_content_decay's classifier with the sign flipped.
Tool name: find_emerging_keywords
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.
Queries with sustained or accelerating growth over several whole periods - find_content_decay's classifier with the sign flipped. Read on impressions, not clicks: an emerging query is one being asked more often, and clicks lag it by however long the page takes to rank, so a query with rising impressions and flat clicks is exactly the row worth acting on. pattern is accelerating when the last rise was bigger than the one before it. noveltyStatus is new when the query drew nothing at the start of the window - on Bing it is always unsupported, because a query appearing there may only have entered a top-N cursor, and on a window Google truncated the same doubt applies to Google. 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. |
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. Keep this low - an emerging query is small by definition. Defaults to 20. |
minRisingPeriods | integer | No | Consecutive rising periods required to qualify. 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."
},
"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": 20,
"description": "Minimum impressions over the whole window. Keep this low - an emerging query is small by definition.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"minRisingPeriods": {
"default": 3,
"description": "Consecutive rising periods required to qualify.",
"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"]
},
"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"
},
"risingPeriods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"growthRatio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"noveltyStatus": {
"type": "string"
},
"latestClicks": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"latestImpressions": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"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",
"risingPeriods",
"growthRatio",
"noveltyStatus",
"latestClicks",
"latestImpressions",
"series"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"bing": {
"anyOf": [
{
"type": "object",
"properties": {
"pattern": {
"type": "string"
},
"risingPeriods": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"growthRatio": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"noveltyStatus": {
"type": "string"
},
"latestClicks": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"latestImpressions": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"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",
"risingPeriods",
"growthRatio",
"noveltyStatus",
"latestClicks",
"latestImpressions",
"series"
],
"additionalProperties": {}
},
{
"type": "null"
}
]
},
"totalLatestImpressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
}
},
"required": [
"label",
"google",
"bing",
"totalLatestImpressions"
],
"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",
"periodWindow",
"rows",
"unsupportedInputs"
],
"additionalProperties": false
}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.
Diagnose traffic losses
For the queries that lost the most clicks, says *why* - and each cause implies a different action, so the class matters more than the number.