Run a custom search-analytics query
The composable read: you choose the grouping, filters, sort and limit instead of asking one of the named questions above.
Tool name: get_advanced_search_analytics
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.
The composable read: you choose the grouping, filters, sort and limit instead of asking one of the named questions above. Use it when no other tool asks what you need - a named tool is better whenever one fits, because it also classifies and explains its rows, and this one only groups and counts.
Dimensions are date, query, page, searchEngine and searchVertical - the columns the data actually has. There is no country or device breakdown for either engine: Bing Webmaster Tools exposes none on any traffic endpoint, and we do not ingest Google's. Every result is whole-property, and switching engine will not change that. Asking for them is an error, not an empty result.
Filters are {field, operator, value} and are ANDed; there is no OR and no nesting. Text fields (query, page) take eq / contains / notContains / startsWith / endsWith, matched case-insensitively; metrics (clicks, impressions, ctr, position) take eq / gt / gte / lt / lte and are applied after the engines are merged, so a threshold is on the row you see. page is matched on its canonical form - no scheme, no www., no trailing slash - so use contains for a section like /blog/ rather than startsWith. Filtering a field you do not group by is fine and is often the point.
position is null on every row unless you group by searchEngine. Google's and Bing's position scales are not confirmed comparable, so a blended figure would not be a real number on either engine. Add searchEngine to dimensions to get it.
Read sources before trusting an absence. A request with no query or page involved is served from the complete daily rollups and agrees exactly with get_performance_trend. Anything grouped or filtered by one of them alone is served from a breakdown Google stores as roughly the top 5,000 rows per day, so a missing row is not evidence of no traffic; using query and page together reads the deeper raw feed instead. sources[].read: false means that engine was not read at all - not attached, or excluded - which is different from measuring zero. truncated covers both your limit and the read's own scan ceiling.
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. |
dimensions | ("date" | "query" | "page" | "searchEngine" | "searchVertical")[] | No | What to group rows by. An empty list returns one row for the whole window. Order is cosmetic. Defaults to ["query"]. |
filters | ({ field, operator, value })[] | No | Predicates, ANDed together. Defaults to []. |
sort | { field, direction } | No | Defaults to clicks descending. A dimension may be sorted on only when it is one of the dimensions grouped by. Rows with no value for the sort field always come last. |
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 | Minimum window impressions for a row to be returned. Applied in storage, so raising it is the cheapest way to keep a wide query - date plus query, say - from hitting the read's scan ceiling. Defaults to 1. |
limit | integer | No | Maximum rows returned. matchedRows reports how many matched before this cut. Defaults to 100. |
searchVertical | "web" | "image" | "video" | No | Pin one Google vertical. Unlike the other tools this has no default and is optional, because 'searchVertical' can also be a dimension - pin it or split by it, not both. Either way Bing is excluded from the response whenever a vertical is involved, since it splits none. |
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."
},
"dimensions": {
"default": ["query"],
"description": "What to group rows by. An empty list returns one row for the whole window. Order is cosmetic.",
"type": "array",
"items": {
"type": "string",
"enum": [
"date",
"query",
"page",
"searchEngine",
"searchVertical"
]
}
},
"filters": {
"default": [],
"description": "Predicates, ANDed together.",
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"query",
"page",
"searchEngine",
"clicks",
"impressions",
"ctr",
"position"
]
},
"operator": {
"type": "string",
"enum": [
"eq",
"contains",
"notContains",
"startsWith",
"endsWith",
"gt",
"gte",
"lt",
"lte"
]
},
"value": {
"type": "string",
"minLength": 1,
"description": "Text to match, or a number for a metric field."
}
},
"required": ["field", "operator", "value"]
}
},
"sort": {
"description": "Defaults to clicks descending. A dimension may be sorted on only when it is one of the dimensions grouped by. Rows with no value for the sort field always come last.",
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"clicks",
"impressions",
"ctr",
"position",
"date",
"query",
"page",
"searchEngine",
"searchVertical"
]
},
"direction": {
"default": "desc",
"type": "string",
"enum": ["asc", "desc"]
}
},
"required": ["field"]
},
"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": 1,
"description": "Minimum window impressions for a row to be returned. Applied in storage, so raising it is the cheapest way to keep a wide query - `date` plus `query`, say - from hitting the read's scan ceiling.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"limit": {
"default": 100,
"description": "Maximum rows returned. `matchedRows` reports how many matched before this cut.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 500
},
"searchVertical": {
"description": "Pin one Google vertical. Unlike the other tools this has no default and is optional, because 'searchVertical' can also be a dimension - pin it or split by it, not both. Either way Bing is excluded from the response whenever a vertical is involved, since it splits none.",
"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": {
"anyOf": [
{
"type": "string",
"enum": ["web", "image", "video"]
},
{
"type": "null"
}
]
},
"currentWindow": {
"type": "object",
"properties": {
"start": {
"type": "string"
},
"end": {
"type": "string"
}
},
"required": ["start", "end"],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"date",
"query",
"page",
"searchEngine",
"searchVertical"
]
}
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"operator": {
"type": "string"
},
"value": {
"type": "string"
}
},
"required": ["field", "operator", "value"],
"additionalProperties": {}
}
},
"sort": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"direction": {
"type": "string"
}
},
"required": ["field", "direction"],
"additionalProperties": {}
},
"limit": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"grain": {
"type": "string",
"enum": ["site", "query", "page", "query_page"]
},
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"searchEngine": {
"type": "string",
"enum": ["google", "bing"]
},
"read": {
"type": "boolean"
},
"datasets": {
"type": "array",
"items": {
"type": "string"
}
},
"rowCapped": {
"type": "boolean"
},
"note": {
"type": "string"
}
},
"required": [
"searchEngine",
"read",
"datasets",
"rowCapped",
"note"
],
"additionalProperties": {}
}
},
"rows": {
"type": "array",
"items": {
"type": "object",
"properties": {
"date": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"page": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"searchEngine": {
"anyOf": [
{
"type": "string",
"enum": ["google", "bing"]
},
{
"type": "null"
}
]
},
"searchVertical": {
"anyOf": [
{
"type": "string",
"enum": ["web", "image", "video"]
},
{
"type": "null"
}
]
},
"clicks": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"impressions": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"ctr": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
]
},
"positionCoverageImpressions": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"required": [
"searchEngine",
"searchVertical",
"clicks",
"impressions",
"ctr",
"position",
"positionCoverageImpressions"
],
"additionalProperties": {}
}
},
"matchedRows": {
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
"truncated": {
"type": "boolean"
},
"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",
"dimensions",
"filters",
"sort",
"limit",
"grain",
"sources",
"rows",
"matchedRows",
"truncated",
"unsupportedInputs"
],
"additionalProperties": false
}Generate search performance report
A Google + Bing performance report for one site or several, assembled by calling the other tools and embedding their responses whole - so a section here is the same answer the tool gives on its own, and you can read it the same way, `unsup…
Create workspace
Create a new workspace.