TOOLS
get_
How are the exact search queries I care about doing week by week?
- Read-only
- No external calls
When to use it
Returns weekly clicks, impressions, click-through rate and average Search Console position for a list of up to 25 exact queries, with a plain verdict comparing the last 4 weeks with the 4 before. Use it to keep an eye on a short list of keywords.
Ask your AI
- Track the queries 'hippo tours' and 'hippo safari kenya' over the last 12 weeks.
- How did my top 5 keywords do week by week over the last year?
- Are clicks for 'best hippo binoculars' growing or declining lately?
Parameters
| Name | Type | Details | What it means |
|---|---|---|---|
propertyId(required) | string | 1–200 characterspattern ^[a-zA-Z0-9._:-]+$ | The ID of the site to read, as returned by list_sites. You must own the site or have been granted access to it. |
queries(required) | array of string | 1–25 items | 1 to 25 different query strings, each up to 512 characters, matched exactly against the stored queries. |
weeks | integer | default 12minimum 8maximum 52 | How many full weeks to return, from 8 to 52. Defaults to 12. Weeks are 7-day blocks ending on the end date. |
end | string | pattern ^\d{4}-\d{2}-\d{2}$ | Optional last day of the latest week (YYYY-MM-DD). Leave it out to end at the latest complete day of data. |
What it returns
For each query, in the order you gave them, one value per week for clicks, impressions, click-through rate and average position, with null for weeks where the query wasn't seen or the week's data is incomplete. Each query also has a verdict (growth, decline, stable, insufficient_volume, not_observed or unavailable) with its confidence (observed, limited or unavailable), the 4-week totals behind it, the click change and the position change. The result also gives the weeks, per-week data coverage, the verdict thresholds, warnings, and an evidence ID for get_evidence_for_change when stored data was used.
Fields of the result:
| Name | Type | Details |
|---|---|---|
id | string or null | 1–200 characterspattern ^[a-zA-Z0-9._:-]+$ |
result | object | — |
result. | "tracked_ | — |
result. | "1. | — |
result. | "1. | — |
result. | "1. | — |
result. | string | 1–200 characterspattern ^[a-zA-Z0-9._:-]+$ |
result. | object | — |
result. | integer | minimum 8maximum 52 |
result. | object or null | — |
result. | array of object | at most 52 items |
result. | object or null | — |
result. | object or null | — |
result. | array of object | at most 52 items |
result. | "byPage" | "byProperty" or null | — |
result. | "ok" | "ok_ | — |
result. | object | — |
result. | integer | minimum 1maximum 25 |
result. | integer | minimum 0maximum 25 |
result. | integer | minimum 0maximum 25 |
result. | boolean | — |
result. | array of object | at most 25 items |
result. | object | — |
result. | array of string | at most 30 items |
result. | array of string | at most 1 items |
input_ | string or null | — |
currency | "current" | "historical" | — |
source | object | — |
source. | "fixture" | "google" | — |
source. | boolean | — |
error | object | returned on its own, instead of the other fields |
error. | "intent_ | — |
error. | boolean | — |
error. | string | — |
error. | string | 1–200 characterspattern ^[a-zA-Z0-9._:-]+$ |
Notes
- Queries must match the stored Search Console text exactly. Nothing is trimmed or lowercased, so 'Hippo' and 'hippo' are different queries; Search Console usually stores queries in lowercase.
- Position is Search Console's average position across all impressions in the week, not a rank checked on a live results page.
- Search Console leaves out rare and anonymized queries, so a query that isn't seen may still have had some searches.
- Growth or decline needs a click change of at least 3 and at least 20% of the earlier 4 weeks, and at least 50 impressions on one side. Position counts as improved or worsened when it moves by 1.0 or more; lower is better.
- Read-only: it reads data QueryHippo has already stored. It does not start a collection, fetch anything or call an AI model.
Description your AI sees
Weekly Search Console clicks, impressions, CTR and source mean position for an exact list of up to 25 stored queries, 8–52 weeks. Categorical verdicts (observed/limited/unavailable). Position is the Search Console mean, not a SERP-measured rank. No external calls.
Full schemas
Input schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"propertyId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-zA-Z0-9._:-]+$"
},
"queries": {
"minItems": 1,
"maxItems": 25,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 512
}
},
"weeks": {
"default": 12,
"type": "integer",
"minimum": 8,
"maximum": 52
},
"end": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"propertyId",
"queries"
],
"additionalProperties": false
}Output schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-zA-Z0-9._:-]+$"
},
{
"type": "null"
}
]
},
"result": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "tracked_query_trends"
},
"schema_version": {
"type": "string",
"const": "1.0.0"
},
"analysis_version": {
"type": "string",
"const": "1.0.0"
},
"policy_version": {
"type": "string",
"const": "1.0.0"
},
"property_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-zA-Z0-9._:-]+$"
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"fixture",
"google"
]
},
"demo": {
"type": "boolean"
}
},
"required": [
"kind",
"demo"
],
"additionalProperties": false
},
"requested_weeks": {
"type": "integer",
"minimum": 8,
"maximum": 52
},
"range": {
"anyOf": [
{
"type": "object",
"properties": {
"start": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"end": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"weeks": {
"maxItems": 52,
"type": "array",
"items": {
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"maximum": 51
},
"start": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"end": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"index",
"start",
"end"
],
"additionalProperties": false
}
},
"source_manifest": {
"anyOf": [
{
"type": "object",
"properties": {
"header_count": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"digest": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"by_source": {
"type": "object",
"properties": {
"performance": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"history": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"none": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"performance",
"history",
"none"
],
"additionalProperties": false
},
"refreshing_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"truncated_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"header_count",
"digest",
"by_source",
"refreshing_days",
"truncated_days"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"coverage": {
"anyOf": [
{
"type": "object",
"properties": {
"expected_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"complete_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"empty_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"missing_days": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"missing_ranges": {
"maxItems": 60,
"type": "array",
"items": {
"type": "object",
"properties": {
"start": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"end": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
}
},
"required": [
"start",
"end"
],
"additionalProperties": false
}
},
"missing_ranges_truncated": {
"type": "boolean"
},
"aggregation": {
"anyOf": [
{
"type": "string",
"enum": [
"byPage",
"byProperty"
]
},
{
"type": "null"
}
]
},
"truncated": {
"type": "boolean"
}
},
"required": [
"expected_days",
"complete_days",
"empty_days",
"missing_days",
"missing_ranges",
"missing_ranges_truncated",
"aggregation",
"truncated"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"week_coverage": {
"maxItems": 52,
"type": "array",
"items": {
"type": "object",
"properties": {
"complete_days": {
"type": "integer",
"minimum": 0,
"maximum": 7
},
"expected_days": {
"type": "number",
"const": 7
},
"truncated": {
"type": "boolean"
}
},
"required": [
"complete_days",
"expected_days",
"truncated"
],
"additionalProperties": false
}
},
"aggregation": {
"anyOf": [
{
"type": "string",
"enum": [
"byPage",
"byProperty"
]
},
{
"type": "null"
}
]
},
"status": {
"type": "string",
"enum": [
"ok",
"ok_with_warnings",
"insufficient_data",
"incompatible_aggregation",
"scan_budget_exceeded"
]
},
"policy": {
"type": "object",
"properties": {
"version": {
"type": "string",
"const": "1.0.0"
},
"compare_weeks": {
"type": "number",
"const": 4
},
"min_impressions": {
"type": "number",
"const": 50
},
"min_click_delta": {
"type": "number",
"const": 3
},
"min_click_delta_percent_of_baseline": {
"type": "number",
"const": 20
},
"position_change_threshold": {
"type": "number",
"const": 1
},
"absent_side_clicks": {
"type": "string",
"const": "not_observed_side_counts_as_zero_for_click_delta"
},
"position_basis": {
"type": "string",
"const": "search_console_impression_weighted_mean_position"
}
},
"required": [
"version",
"compare_weeks",
"min_impressions",
"min_click_delta",
"min_click_delta_percent_of_baseline",
"position_change_threshold",
"absent_side_clicks",
"position_basis"
],
"additionalProperties": false
},
"requested_count": {
"type": "integer",
"minimum": 1,
"maximum": 25
},
"returned_count": {
"type": "integer",
"minimum": 0,
"maximum": 25
},
"omitted_count": {
"type": "integer",
"minimum": 0,
"maximum": 25
},
"byte_limited": {
"type": "boolean"
},
"queries": {
"maxItems": 25,
"type": "array",
"items": {
"type": "object",
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 512
},
"observed_weeks": {
"type": "integer",
"minimum": 0,
"maximum": 52
},
"clicks": {
"maxItems": 52,
"type": "array",
"items": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"impressions": {
"maxItems": 52,
"type": "array",
"items": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
}
},
"ctr": {
"maxItems": 52,
"type": "array",
"items": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 1
},
{
"type": "null"
}
]
}
},
"position": {
"maxItems": 52,
"type": "array",
"items": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"verdict": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"growth",
"decline",
"stable",
"insufficient_volume",
"not_observed",
"unavailable"
]
},
"confidence": {
"type": "string",
"enum": [
"observed",
"limited",
"unavailable"
]
},
"actionable": {
"type": "boolean"
},
"baseline": {
"anyOf": [
{
"type": "object",
"properties": {
"observed_weeks": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"clicks": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"impressions": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 1
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"observed_weeks",
"clicks",
"impressions",
"ctr",
"position"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"current": {
"anyOf": [
{
"type": "object",
"properties": {
"observed_weeks": {
"type": "integer",
"minimum": 0,
"maximum": 4
},
"clicks": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"impressions": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"ctr": {
"anyOf": [
{
"type": "number",
"minimum": 0,
"maximum": 1
},
{
"type": "null"
}
]
},
"position": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"required": [
"observed_weeks",
"clicks",
"impressions",
"ctr",
"position"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"click_delta": {
"anyOf": [
{
"type": "integer",
"minimum": -9007199254740991,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"position_change": {
"type": [
"number",
"null"
]
},
"position_direction": {
"anyOf": [
{
"type": "string",
"enum": [
"improved",
"worsened",
"stable"
]
},
{
"type": "null"
}
]
}
},
"required": [
"kind",
"confidence",
"actionable",
"baseline",
"current",
"click_delta",
"position_change",
"position_direction"
],
"additionalProperties": false
}
},
"required": [
"query",
"observed_weeks",
"clicks",
"impressions",
"ctr",
"position",
"verdict"
],
"additionalProperties": false
}
},
"scan_policy": {
"type": "object",
"properties": {
"max_history_rows": {
"type": "number",
"const": 6000000
},
"statement_timeout_ms": {
"type": "number",
"const": 5000
}
},
"required": [
"max_history_rows",
"statement_timeout_ms"
],
"additionalProperties": false
},
"warnings": {
"maxItems": 30,
"type": "array",
"items": {
"type": "string",
"maxLength": 200
}
},
"evidence_ids": {
"maxItems": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
}
},
"required": [
"kind",
"schema_version",
"analysis_version",
"policy_version",
"property_id",
"source",
"requested_weeks",
"range",
"weeks",
"source_manifest",
"coverage",
"week_coverage",
"aggregation",
"status",
"policy",
"requested_count",
"returned_count",
"omitted_count",
"byte_limited",
"queries",
"scan_policy",
"warnings",
"evidence_ids"
],
"additionalProperties": false
},
"input_fingerprint": {
"type": [
"string",
"null"
]
},
"currency": {
"type": "string",
"enum": [
"current",
"historical"
]
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"fixture",
"google"
]
},
"demo": {
"type": "boolean"
}
},
"required": [
"kind",
"demo"
],
"additionalProperties": false
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"intent_history_unavailable",
"intent_accounting_pending",
"google_reconnect_required",
"unauthorized",
"not_found_or_forbidden",
"dependency_unavailable",
"quota_exceeded",
"invalid_input",
"invalid_source",
"stale_attempt",
"conflict",
"unknown_commit",
"not_configured"
]
},
"retryable": {
"type": "boolean"
},
"message": {
"type": "string"
},
"correlation_id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-zA-Z0-9._:-]+$"
}
},
"required": [
"code",
"retryable",
"message",
"correlation_id"
],
"additionalProperties": false
}
},
"additionalProperties": false,
"anyOf": [
{
"required": [
"id",
"result",
"input_fingerprint",
"currency",
"source"
],
"not": {
"required": [
"error"
]
}
},
{
"required": [
"error"
],
"maxProperties": 1
}
]
}