# get_tracked_query_trends

> 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…

**Source:** [https://queryhippo.com/docs/tools/get_tracked_query_trends](https://queryhippo.com/docs/tools/get_tracked_query_trends)

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 characters; pattern ^[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 12; minimum 8; maximum 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 characters; pattern ^[a-zA-Z0-9._:-]+$ |
| `result` | `object` | — |
| `result.kind` | `"tracked_query_trends"` | — |
| `result.schema_version` | `"1.0.0"` | — |
| `result.analysis_version` | `"1.0.0"` | — |
| `result.policy_version` | `"1.0.0"` | — |
| `result.property_id` | `string` | 1–200 characters; pattern ^[a-zA-Z0-9._:-]+$ |
| `result.source` | `object` | — |
| `result.requested_weeks` | `integer` | minimum 8; maximum 52 |
| `result.range` | `object or null` | — |
| `result.weeks` | `array of object` | at most 52 items |
| `result.source_manifest` | `object or null` | — |
| `result.coverage` | `object or null` | — |
| `result.week_coverage` | `array of object` | at most 52 items |
| `result.aggregation` | `"byPage" \| "byProperty" or null` | — |
| `result.status` | `"ok" \| "ok_with_warnings" \| "insufficient_data" \| "incompatible_aggregation" \| "scan_budget_exceeded"` | — |
| `result.policy` | `object` | — |
| `result.requested_count` | `integer` | minimum 1; maximum 25 |
| `result.returned_count` | `integer` | minimum 0; maximum 25 |
| `result.omitted_count` | `integer` | minimum 0; maximum 25 |
| `result.byte_limited` | `boolean` | — |
| `result.queries` | `array of object` | at most 25 items |
| `result.scan_policy` | `object` | — |
| `result.warnings` | `array of string` | at most 30 items |
| `result.evidence_ids` | `array of string` | at most 1 items |
| `input_fingerprint` | `string or null` | — |
| `currency` | `"current" \| "historical"` | — |
| `source` | `object` | — |
| `source.kind` | `"fixture" \| "google"` | — |
| `source.demo` | `boolean` | — |
| `error` | `object` | returned on its own, instead of the other fields |
| `error.code` | `"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"` | — |
| `error.retryable` | `boolean` | — |
| `error.message` | `string` | — |
| `error.correlation_id` | `string` | 1–200 characters; pattern ^[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
    }
  ]
}
```