Find content gaps
The tool finds topics the site should cover. It returns two parts, and each row says which part it came from. The first part is always returned, and it is free. Those rows are queries the site was shown for, above the impression threshold, where no page ranks well. A page ranks poorly if its position is worse than positionThreshold, or if it does not rank. The rows are in rows. The second part is returned only if includeUncovered is true. Those topics come from the workspace's confirmed products and audiences, and the site has no page for them. They are in uncovered. The first part cannot see these topics. Both engines list a query only if the site already earned an impression for it, so a topic with no page produces no search row. A missing query is not evidence of a gap. The second part spends money on every call. It makes one model call to expand the workspace's content, plus one keyword-volume request per engine. It is capped per workspace per day, and it asks for confirmation first. Read uncoveredStatus before you treat an empty uncovered list as a finding. not_requested means you did not ask for the second part. unavailable means the workspace has no confirmed products or audiences to build a topic from. failed means the expansion could not run. None of those three means the site has no uncovered demand. Second-part rows are grouped by topic, with query variants nested under each topic. recommendedAction is the action to take. create means nothing of yours is close to the topic. refresh means a page of yours is close, so expand the page in pageToRefresh. Publishing a second page would compete with it. verify_inventory means fewer pages were searched than the site has, so the absence is a limit of the search. Read coverage.nearestDistance with the verdict. The distance thresholds are stated. They are not tuned to this site. Every first-part row has a cannibalizationStatus. "No page ranks well" and "several of our pages split the query" look the same here and call for opposite actions. confirmed sets gapType to cannibalized and lists competingPages. Consolidate those pages. Strengthening one of them is the wrong move. See detect_keyword_cannibalization. possible names an unread sitemap URL in suspectedPages. Open that URL before you optimize, because the two pages may be competing. none means the row is cleared. One page ranks, and nothing else in the sitemap targets the query, so optimizing that page is the right move. unknown means the site has no usable sitemap, so the row is a candidate to optimize. See unsupportedInputs. 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_content_gapsThe tool finds topics the site should cover. It returns two parts, and each row says which part it came from.
The first part is always returned, and it is free. Those rows are queries the site was shown for, above the impression threshold, where no page ranks well. A page ranks poorly if its position is worse than positionThreshold, or if it does not rank. The rows are in rows.
The second part is returned only if includeUncovered is true. Those topics come from the workspace's confirmed products and audiences, and the site has no page for them. They are in uncovered. The first part cannot see these topics. Both engines list a query only if the site already earned an impression for it, so a topic with no page produces no search row. A missing query is not evidence of a gap.
The second part spends money on every call. It makes one model call to expand the workspace's content, plus one keyword-volume request per engine. It is capped per workspace per day, and it asks for confirmation first.
Read uncoveredStatus before you treat an empty uncovered list as a finding. not_requested means you did not ask for the second part. unavailable means the workspace has no confirmed products or audiences to build a topic from. failed means the expansion could not run. None of those three means the site has no uncovered demand.
Second-part rows are grouped by topic, with query variants nested under each topic. recommendedAction is the action to take. create means nothing of yours is close to the topic. refresh means a page of yours is close, so expand the page in pageToRefresh. Publishing a second page would compete with it. verify_inventory means fewer pages were searched than the site has, so the absence is a limit of the search. Read coverage.nearestDistance with the verdict. The distance thresholds are stated. They are not tuned to this site.
Every first-part row has a cannibalizationStatus. "No page ranks well" and "several of our pages split the query" look the same here and call for opposite actions.
confirmed sets gapType to cannibalized and lists competingPages. Consolidate those pages. Strengthening one of them is the wrong move. See detect_keyword_cannibalization. possible names an unread sitemap URL in suspectedPages. Open that URL before you optimize, because the two pages may be competing.
none means the row is cleared. One page ranks, and nothing else in the sitemap targets the query, so optimizing that page is the right move. unknown means the site has no usable sitemap, so the row is a candidate to optimize. See unsupportedInputs.
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. |
positionThreshold | number | No | A query ranking worse than this position counts as a gap. Defaults to 15. |
minImpressions | integer | No | Minimum current-window impressions for a query to count as visible. Defaults to 10. |
limit | integer | No | Maximum rows to return, sorted by relevance. Defaults to 50. |
includeUncovered | boolean | No | Also return topics the site has no page for. The tool expands the workspace's confirmed products, audiences, and pain points into search topics, then reports the ones with no page. This spends money: one model call, plus one keyword-volume request per engine. It is capped per workspace per day, and it asks for confirmation first. Leave this off to keep the free query list only. Defaults to false. |
uncoveredLimit | integer | No | Maximum half-B topics to return, highest demand first. Defaults to 20. |
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" }, "positionThreshold": { "default": 15, "description": "A query ranking worse than this position counts as a gap.", "type": "number", "minimum": 1 }, "minImpressions": { "default": 10, "description": "Minimum current-window impressions for a query to count as visible.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "default": 50, "description": "Maximum rows to return, sorted by relevance.", "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "includeUncovered": { "default": false, "description": "Also return topics the site has no page for. The tool expands the workspace's confirmed products, audiences, and pain points into search topics, then reports the ones with no page. This spends money: one model call, plus one keyword-volume request per engine. It is capped per workspace per day, and it asks for confirmation first. Leave this off to keep the free query list only.", "type": "boolean" }, "uncoveredLimit": { "default": 20, "description": "Maximum half-B topics to return, highest demand first.", "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "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 }, "rows": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" }, "google": { "anyOf": [ { "type": "object", "properties": { "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "impressions", "clicks", "position" ], "additionalProperties": {} }, { "type": "null" } ] }, "bing": { "anyOf": [ { "type": "object", "properties": { "impressions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "clicks": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "position": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "impressions", "clicks", "position" ], "additionalProperties": {} }, { "type": "null" } ] }, "gapType": { "type": "string" }, "cannibalizationStatus": { "type": "string" }, "competingPages": { "type": "array", "items": { "type": "string" } }, "suspectedPages": { "type": "array", "items": { "type": "string" } } }, "required": [ "label", "google", "bing", "gapType", "cannibalizationStatus", "competingPages", "suspectedPages" ], "additionalProperties": {} } }, "uncovered": { "type": "array", "items": { "type": "object", "properties": { "gapType": { "type": "string" }, "topic": { "type": "string" }, "seed": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seedKind": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mergedFrom": { "type": "array", "items": { "type": "string" } }, "queries": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" }, "searchVolume": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "demandSource": { "type": "string" }, "competition": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "competitionIndex": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "cpc": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "nearestDistance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "query", "searchVolume", "demandSource", "competition", "competitionIndex", "cpc", "nearestDistance" ], "additionalProperties": {} } }, "coverage": { "type": "object", "properties": { "verdict": { "type": "string" }, "test": { "type": "string" }, "nearestPage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "nearestDistance": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "nearestExcerpt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "searchedPages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "siteKnownPages": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "siteKnownPagesReliable": { "type": "boolean" }, "inventoryComplete": { "type": "boolean" }, "coveredMaxDistance": { "type": "number" }, "adjacentMaxDistance": { "type": "number" } }, "required": [ "verdict", "test", "nearestPage", "nearestDistance", "nearestExcerpt", "searchedPages", "siteKnownPages", "siteKnownPagesReliable", "inventoryComplete", "coveredMaxDistance", "adjacentMaxDistance" ], "additionalProperties": {} }, "demand": { "type": "object", "properties": { "searchVolume": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "source": { "type": "string" }, "variantsPriced": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "variantsTotal": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "searchVolume", "source", "variantsPriced", "variantsTotal" ], "additionalProperties": {} }, "cannibalizationStatus": { "type": "string" }, "pageToRefresh": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "recommendedAction": { "type": "string" } }, "required": [ "gapType", "topic", "seed", "seedKind", "mergedFrom", "queries", "coverage", "demand", "cannibalizationStatus", "pageToRefresh", "recommendedAction" ], "additionalProperties": {} } }, "uncoveredStatus": { "type": "object", "properties": { "status": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "topicsProposed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "topicsReturned": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "topicsCovered": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "topicsVisibleInSearch": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "queriesExpanded": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "costUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "status", "reason", "topicsProposed", "topicsReturned", "topicsCovered", "topicsVisibleInSearch", "queriesExpanded", "costUsd" ], "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", "rows", "uncovered", "uncoveredStatus", "unsupportedInputs" ], "additionalProperties": false}