Find new and lost keywords
The tool marks each search query as new, lost, improved, declined, or stable between this window and the window of the same length just before it. It marks Google and Bing separately. It leaves out a query if neither engine shows a real change. Bing only shares its top queries, ranked by traffic and limited to a set number of results. A query that drops to zero clicks cannot be told apart from a query that fell below that limit, so the tool marks that Bing result as unsupported. In the output, status is "unsupported". The same limit applies to Google when Google cut the rows in the window. If Google cut the current window, the tool marks a missing query as unsupported. Do not read that row as lost. If Google cut the earlier window, the tool marks a query that shows up only now as unsupported. Do not read that row as new. The tool keeps an improved or declined mark, because those marks compare two rows that both exist. Google keeps about 5,000 rows per day for each single breakdown once a day is more than about three days old. On a large site the tool is reading the top queries or pages by impressions. Google no longer stores the rest. If that applies to this window, the response names the dates in unsupportedInputs. A missing row means it was outside that list. Google no longer has the row, so there is nothing further to fetch.
find_new_and_lost_keywordsThe tool marks each search query as new, lost, improved, declined, or stable between this window and the window of the same length just before it.
It marks Google and Bing separately. It leaves out a query if neither engine shows a real change.
Bing only shares its top queries, ranked by traffic and limited to a set number of results. A query that drops to zero clicks cannot be told apart from a query that fell below that limit, so the tool marks that Bing result as unsupported. In the output, status is "unsupported".
The same limit applies to Google when Google cut the rows in the window. If Google cut the current window, the tool marks a missing query as unsupported. Do not read that row as lost. If Google cut the earlier window, the tool marks a query that shows up only now as unsupported. Do not read that row as new.
The tool keeps an improved or declined mark, because those marks compare two rows that both exist.
Google keeps about 5,000 rows per day for each single breakdown once a day is more than about three days old. On a large site the tool is reading the top queries or pages by impressions. Google no longer stores the rest.
If that applies to this window, the response names the dates in unsupportedInputs. A missing row means it was outside that list. Google no longer has the row, so there is nothing further to fetch.
Parameters
| Parameter | Type | Required | Notes |
|---|---|---|---|
site | string | Yes | The site to look up, as a bare domain ("example.com") or a URL. The tool strips the scheme, www, path, and trailing slash. The site must belong to a workspace you own. Call list_sites first if you are not sure of the exact domain. |
windowDays | integer | No | Length of the current window, in days. Defaults to 28. |
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 | A period needs at least this many impressions to count as visible. Below it, the row is too thin to mark as new or lost. Defaults to 5. |
limit | integer | No | Maximum rows to return, sorted by relevance. Defaults to 50. |
searchVertical | "web" | "image" | "video" | No | Which Google search type to read: web (the default), image, or video. Bing Webmaster Tools does not split search types on any traffic report, so image and video return Google only. The response records that Bing was left out, in unsupportedInputs. A missing Bing number then means Bing was not measured. Defaults to "web". |
Full input JSON SchemaTypes, defaults and validation rules
{ "$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. The tool strips the scheme, www, path, and trailing slash. The site must belong to a workspace you own. Call list_sites first if you are not sure of the exact domain." }, "windowDays": { "default": 28, "description": "Length of the current window, in days.", "type": "integer", "exclusiveMinimum": 0, "maximum": 365 }, "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": 5, "description": "A period needs at least this many impressions to count as visible. Below it, the row is too thin to mark as new or lost.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "default": 50, "description": "Maximum rows to return, sorted by relevance.", "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "searchVertical": { "default": "web", "description": "Which Google search type to read: web (the default), image, or video. Bing Webmaster Tools does not split search types on any traffic report, so image and video return Google only. The response records that Bing was left out, in unsupportedInputs. A missing Bing number then means Bing was not measured.", "type": "string", "enum": [ "web", "image", "video" ] } }, "required": [ "site" ]}Response
Full output JSON SchemaEvery field the response can contain
{ "$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" ] }, "currentWindow": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "comparisonWindow": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "rows": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "google": { "type": "object", "properties": { "status": { "type": "string" }, "current": { "type": "object", "properties": { "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "position" ], "additionalProperties": {} }, "previous": { "type": "object", "properties": { "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "position" ], "additionalProperties": {} }, "deltaClicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deltaImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deltaPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "status", "current", "previous", "deltaClicks", "deltaImpressions", "deltaPosition" ], "additionalProperties": {} }, "bing": { "type": "object", "properties": { "status": { "type": "string" }, "current": { "type": "object", "properties": { "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "position" ], "additionalProperties": {} }, "previous": { "type": "object", "properties": { "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "clicks", "impressions", "position" ], "additionalProperties": {} }, "deltaClicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deltaImpressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "deltaPosition": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "status", "current", "previous", "deltaClicks", "deltaImpressions", "deltaPosition" ], "additionalProperties": {} } }, "required": [ "label", "google", "bing" ], "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", "currentWindow", "comparisonWindow", "rows", "unsupportedInputs" ], "additionalProperties": false}