Topic cluster performance
get_topic_cluster_performanceMeasures a property's topic clusters: clicks, impressions, CTR, impression-weighted average position, matched query count and share of clicks per cluster, plus an "unclustered" bucket for queries no cluster claims. Pass clusterId to drill into one cluster's top queries (each row lists which of the cluster's keywords matched). A cluster keyword is a case-insensitive substring unless wrapped in slashes (/seo ?tools/), which makes it a regex. IMPORTANT: clusters may OVERLAP (a query matching two clusters counts fully in both), so cluster totals do not sum to the property total; overlappingQueries reports how many queries are double-counted. Matching runs over the top scanLimit queries by clicks (default 50,000), read from the GSC Wizard ClickHouse warehouse when available (which scans at most 50,000 queries; scanLimit in the response is the limit actually applied), otherwise the live Search Console API (see dataSource). Use list_topic_clusters / create_topic_cluster to see or add the definitions this reports on. Date range is optional: omit startDate/endDate to analyze the last 28 settled days (data lags ~2-3 days).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Row cap for the clusterId query drill-down. | |
| endDate | No | Optional. Window end as YYYY-MM-DD (e.g. 2026-05-31). You do NOT need to know today's date or the latest available date: omit this and the server uses the latest settled Search Console date (data lags ~2-3 days behind today). Never pass null or the string "null". | |
| siteUrl | Yes | ||
| clusterId | No | Drill into one cluster: returns its top matched queries instead of the per-cluster aggregates. Accepts a topic cluster id or the literal "unclustered". | |
| scanLimit | No | How many top queries by clicks to match against the clusters. Raise it when a long-tail property reports `truncated: true`. Clamped at 50,000 on the ClickHouse path. | |
| startDate | No | Optional. Window start as YYYY-MM-DD (e.g. 2026-05-03). You do NOT need to know today's date. Omit BOTH startDate and endDate to analyze the last 28 settled days automatically (Search Console data lags ~2-3 days). Never pass null or the string "null". | |
| searchType | No | web | |
| comparisonEndDate | No | Optional. End of the comparison period as YYYY-MM-DD. Provide BOTH comparison dates to compare two periods; omit both for no comparison (prev* fields are then 0 and hasComparison false). | |
| comparisonStartDate | No | Optional. Start of the comparison period as YYYY-MM-DD. Provide BOTH comparison dates to compare two periods; omit both for no comparison (prev* fields are then 0 and hasComparison false). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | ||
| range | No | ||
| queries | No | ||
| siteUrl | No | ||
| clusters | No | ||
| clusterId | No | ||
| scanLimit | No | ||
| truncated | No | ||
| dataSource | No | ||
| searchType | No | ||
| clusterName | No | ||
| overlapNote | No | ||
| unclustered | No | ||
| clusterCount | No | ||
| dataMaturity | No | ||
| hasComparison | No | ||
| scannedClicks | No | ||
| scannedQueries | No | ||
| settledThrough | No | ||
| comparisonRange | No | ||
| matchedQueryCount | No | ||
| overlappingQueries | No | ||
| warehouseLatestDate | No |