# find_search_opportunities

> Returns a ranked list of observed queries or pages that meet clear review rules: clicks declined, many impressions with a low click-through rate compared with…

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

Which queries or pages are worth reviewing because clicks fell, click-through is low, or visibility improved?

- Read-only
- No external calls

## When to use it

Returns a ranked list of observed queries or pages that meet clear review rules: clicks declined, many impressions with a low click-through rate compared with similar entries, or average position improved. Use it to decide what to look at first; it does not predict gains or change your site.

## Ask your AI

- Which queries on my site lost the most clicks in the last 28 days?
- Find pages with lots of impressions but a low click-through rate.
- Show search opportunities for my site over the last 7 days, pages only.

## 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. |
| `threshold_mode` | `"scaled" \| "fixed"` | default "scaled" | "scaled" (default) sizes the review thresholds to your site's traffic in the current window; "fixed" uses the same fixed defaults for every site. |
| `thresholds` | `object` | — | Optional overrides for individual rules, such as min_impressions or ctr_max_ratio. Any rule you set replaces the scaled or fixed value. |
| `thresholds.min_impressions` | `integer` | minimum 1; maximum 1000000 | Part of thresholds; see the thresholds row. |
| `thresholds.decline_min_clicks` | `integer` | minimum 1; maximum 1000000 | Part of thresholds; see the thresholds row. |
| `thresholds.decline_max_percent` | `integer` | minimum -100; maximum -1 | Part of thresholds; see the thresholds row. |
| `thresholds.peer_min_count` | `integer` | minimum 1; maximum 1000 | Part of thresholds; see the thresholds row. |
| `thresholds.peer_min_impressions` | `integer` | minimum 1; maximum 100000000 | Part of thresholds; see the thresholds row. |
| `thresholds.ctr_max_ratio` | `number` | minimum 0.05; maximum 0.95 | Part of thresholds; see the thresholds row. |
| `thresholds.visibility_min_improvement` | `number` | minimum 0.5; maximum 50 | Part of thresholds; see the thresholds row. |
| `thresholds.visibility_max_current_position` | `number` | minimum 1; maximum 100 | Part of thresholds; see the thresholds row. |
| `entity` | `"query" \| "page"` | default "query" | Whether to review search queries ("query", the default) or pages ("page"). |
| `days` | `7 or 28` | — | Compare the latest 7 or 28 complete days with the 7 or 28 days just before them. Leave it out to use 28, and don't combine it with baseline/current. |
| `baseline` | `object` | — | Optional custom earlier window as { start, end } dates (YYYY-MM-DD). Give it together with current; both windows must be the same length and must not overlap. |
| `baseline.start` (required) | `string` | pattern ^\\d{4}-\\d{2}-\\d{2}$ | Part of baseline; see the baseline row. |
| `baseline.end` (required) | `string` | pattern ^\\d{4}-\\d{2}-\\d{2}$ | Part of baseline; see the baseline row. |
| `current` | `object` | — | Optional custom later window as { start, end } dates (YYYY-MM-DD). Give it together with baseline; it must start after baseline ends. |
| `current.start` (required) | `string` | pattern ^\\d{4}-\\d{2}-\\d{2}$ | Part of current; see the current row. |
| `current.end` (required) | `string` | pattern ^\\d{4}-\\d{2}-\\d{2}$ | Part of current; see the current row. |
| `limit` | `integer` | default 20; minimum 1; maximum 50 | How many results to return, from 1 to 50. Defaults to 20. |
| `reasons` | `array of "clicks_declined" \| "high_impressions_low_ctr" \| "visibility_improved"` | 1–3 items | Optional filter to one to three reasons: clicks_declined, high_impressions_low_ctr or visibility_improved. Leave it out to include all three. |

## What it returns

The requested number of queries or pages (20 by default, at most 50), each with its clicks, impressions, click-through rate and average position in both windows, and the rule or rules that picked it with the numbers behind each one. Page results also say whether the page is listed in your latest sitemap. The result also gives the windows compared, the thresholds used, data coverage, how many candidates were found and left out, any 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` | `"search_opportunities"` | — |
| `result.schema_version` | `"2.0.0"` | — |
| `result.analysis_version` | `"2.0.0"` | — |
| `result.policy_version` | `"2.0.0"` | — |
| `result.property_id` | `string` | 1–200 characters; pattern ^[a-zA-Z0-9._:-]+$ |
| `result.entity` | `"query" \| "page"` | — |
| `result.source` | `object` | — |
| `result.windows` | `object or null` | — |
| `result.filters` | `object` | — |
| `result.source_revisions` | `array of object` | at most 180 items |
| `result.coverage` | `object or null` | — |
| `result.aggregation` | `"byPage" \| "byProperty" or null` | — |
| `result.selection_policy` | `object` | — |
| `result.status` | `"ok" \| "ok_with_warnings" \| "insufficient_data" \| "incompatible_aggregation" \| "scan_budget_exceeded"` | — |
| `result.total_candidate_entities` | `integer` | minimum 0 |
| `result.requested_limit` | `integer` | minimum 1; maximum 50 |
| `result.returned_count` | `integer` | minimum 0 |
| `result.omitted_count` | `integer` | minimum 0 |
| `result.byte_limited` | `boolean` | — |
| `result.candidates` | `array of object` | at most 50 items |
| `result.scan_policy` | `object` | — |
| `result.warnings` | `array of string` | at most 30 items |
| `result.evidence_ids` | `array of string` | at most 1 items |
| `result.sitemap` | `object` | — |
| `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

- By default the thresholds scale to your site's traffic (threshold_mode "scaled"), so small sites still get results. You can override any threshold, or use the fixed defaults.
- Page results say whether each page is in your latest sitemap. Sitemap changes in the same period are shown alongside, not as proven causes.
- 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

> Find deterministic observed query/page review candidates with volume-scaled thresholds, per-call overrides and disclosed decline, leave-one-out CTR and visibility rules. Complete admitted finalized web rows; no predicted lift or site edits. Page candidates note whether they are in the latest sitemap.

## 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._:-]+$"
    },
    "threshold_mode": {
      "default": "scaled",
      "type": "string",
      "enum": [
        "scaled",
        "fixed"
      ]
    },
    "thresholds": {
      "type": "object",
      "properties": {
        "min_impressions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000
        },
        "decline_min_clicks": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000
        },
        "decline_max_percent": {
          "type": "integer",
          "minimum": -100,
          "maximum": -1
        },
        "peer_min_count": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "peer_min_impressions": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100000000
        },
        "ctr_max_ratio": {
          "type": "number",
          "minimum": 0.05,
          "maximum": 0.95
        },
        "visibility_min_improvement": {
          "type": "number",
          "minimum": 0.5,
          "maximum": 50
        },
        "visibility_max_current_position": {
          "type": "number",
          "minimum": 1,
          "maximum": 100
        }
      },
      "additionalProperties": false
    },
    "entity": {
      "default": "query",
      "type": "string",
      "enum": [
        "query",
        "page"
      ]
    },
    "days": {
      "anyOf": [
        {
          "type": "number",
          "const": 7
        },
        {
          "type": "number",
          "const": 28
        }
      ]
    },
    "baseline": {
      "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
    },
    "current": {
      "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
    },
    "limit": {
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "reasons": {
      "minItems": 1,
      "maxItems": 3,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "clicks_declined",
          "high_impressions_low_ctr",
          "visibility_improved"
        ]
      }
    }
  },
  "required": [
    "propertyId"
  ],
  "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": "search_opportunities"
        },
        "schema_version": {
          "type": "string",
          "const": "2.0.0"
        },
        "analysis_version": {
          "type": "string",
          "const": "2.0.0"
        },
        "policy_version": {
          "type": "string",
          "const": "2.0.0"
        },
        "property_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 200,
          "pattern": "^[a-zA-Z0-9._:-]+$"
        },
        "entity": {
          "type": "string",
          "enum": [
            "query",
            "page"
          ]
        },
        "source": {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "fixture",
                "google"
              ]
            },
            "demo": {
              "type": "boolean"
            }
          },
          "required": [
            "kind",
            "demo"
          ],
          "additionalProperties": false
        },
        "windows": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "baseline": {
                  "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
                },
                "current": {
                  "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
                }
              },
              "required": [
                "baseline",
                "current"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "filters": {
          "type": "object",
          "properties": {
            "search_type": {
              "type": "string",
              "const": "web"
            },
            "profile": {
              "type": "string",
              "enum": [
                "query",
                "page"
              ]
            },
            "reasons": {
              "minItems": 1,
              "maxItems": 3,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "clicks_declined",
                  "high_impressions_low_ctr",
                  "visibility_improved"
                ]
              }
            }
          },
          "required": [
            "search_type",
            "profile",
            "reasons"
          ],
          "additionalProperties": false
        },
        "source_revisions": {
          "maxItems": 180,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "date": {
                "type": "string",
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
              },
              "search_type": {
                "type": "string",
                "const": "web"
              },
              "profile": {
                "type": "string",
                "enum": [
                  "query",
                  "page"
                ]
              },
              "source": {
                "type": "string",
                "enum": [
                  "performance",
                  "history",
                  "none"
                ]
              },
              "revision_id": {
                "anyOf": [
                  {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 200,
                    "pattern": "^[a-zA-Z0-9._:-]+$"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "row_count": {
                "anyOf": [
                  {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "aggregation": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "byPage",
                      "byProperty",
                      "auto"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "truncated": {
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "truncation_basis": {
                "type": "string",
                "enum": [
                  "persisted",
                  "row_ceiling_inferred",
                  "unknown"
                ]
              },
              "extraction_complete": {
                "type": "boolean"
              },
              "metric_usable": {
                "type": "boolean"
              },
              "refresh_state": {
                "type": "string",
                "enum": [
                  "waiting",
                  "active",
                  "failed",
                  "none"
                ]
              },
              "availability": {
                "type": "string",
                "enum": [
                  "observed",
                  "completed_empty",
                  "missing",
                  "unsupported"
                ]
              },
              "error_code": {
                "anyOf": [
                  {
                    "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"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "date",
              "search_type",
              "profile",
              "source",
              "revision_id",
              "row_count",
              "aggregation",
              "truncated",
              "truncation_basis",
              "extraction_complete",
              "metric_usable",
              "refresh_state",
              "availability",
              "error_code"
            ],
            "additionalProperties": false
          }
        },
        "coverage": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "baseline": {
                  "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_dates": {
                      "maxItems": 90,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                      }
                    },
                    "aggregation": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "byPage",
                            "byProperty"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "truncated": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "expected_days",
                    "complete_days",
                    "empty_days",
                    "missing_dates",
                    "aggregation",
                    "truncated"
                  ],
                  "additionalProperties": false
                },
                "current": {
                  "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_dates": {
                      "maxItems": 90,
                      "type": "array",
                      "items": {
                        "type": "string",
                        "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                      }
                    },
                    "aggregation": {
                      "anyOf": [
                        {
                          "type": "string",
                          "enum": [
                            "byPage",
                            "byProperty"
                          ]
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "truncated": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "expected_days",
                    "complete_days",
                    "empty_days",
                    "missing_dates",
                    "aggregation",
                    "truncated"
                  ],
                  "additionalProperties": false
                }
              },
              "required": [
                "baseline",
                "current"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "aggregation": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "byPage",
                "byProperty"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "selection_policy": {
          "type": "object",
          "properties": {
            "version": {
              "type": "string",
              "const": "2.0.0"
            },
            "min_impressions": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000
            },
            "decline_min_clicks": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000000
            },
            "decline_max_delta": {
              "type": "integer",
              "minimum": -1000000,
              "maximum": -1
            },
            "decline_max_percent": {
              "type": "integer",
              "minimum": -100,
              "maximum": -1
            },
            "block_days": {
              "type": "number",
              "const": 7
            },
            "persistence_min_days": {
              "type": "number",
              "const": 14
            },
            "persistence_min_blocks": {
              "type": "number",
              "const": 2
            },
            "block_decline_max_percent": {
              "type": "number",
              "const": -10
            },
            "persistence_min_fraction": {
              "type": "number",
              "const": 0.75
            },
            "position_bands": {
              "type": "array",
              "items": [
                {
                  "type": "array",
                  "items": [
                    {
                      "type": "number",
                      "const": 1
                    },
                    {
                      "type": "number",
                      "const": 3
                    }
                  ],
                  "additionalItems": false,
                  "minItems": 2,
                  "maxItems": 2
                },
                {
                  "type": "array",
                  "items": [
                    {
                      "type": "number",
                      "const": 3
                    },
                    {
                      "type": "number",
                      "const": 6
                    }
                  ],
                  "additionalItems": false,
                  "minItems": 2,
                  "maxItems": 2
                },
                {
                  "type": "array",
                  "items": [
                    {
                      "type": "number",
                      "const": 6
                    },
                    {
                      "type": "number",
                      "const": 11
                    }
                  ],
                  "additionalItems": false,
                  "minItems": 2,
                  "maxItems": 2
                },
                {
                  "type": "array",
                  "items": [
                    {
                      "type": "number",
                      "const": 11
                    },
                    {
                      "type": "number",
                      "const": 21
                    }
                  ],
                  "additionalItems": false,
                  "minItems": 2,
                  "maxItems": 2
                },
                {
                  "type": "array",
                  "items": [
                    {
                      "type": "number",
                      "const": 21
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "additionalItems": false,
                  "minItems": 2,
                  "maxItems": 2
                }
              ],
              "additionalItems": false,
              "minItems": 5,
              "maxItems": 5
            },
            "peer_min_count": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1000
            },
            "peer_min_impressions": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000000
            },
            "ctr_max_ratio": {
              "type": "number",
              "minimum": 0.05,
              "maximum": 0.95
            },
            "visibility_min_improvement": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 50
            },
            "visibility_max_current_position": {
              "type": "number",
              "minimum": 1,
              "maximum": 100
            },
            "reason_order": {
              "type": "array",
              "items": [
                {
                  "type": "string",
                  "const": "clicks_declined"
                },
                {
                  "type": "string",
                  "const": "high_impressions_low_ctr"
                },
                {
                  "type": "string",
                  "const": "visibility_improved"
                }
              ],
              "additionalItems": false,
              "minItems": 3,
              "maxItems": 3
            },
            "peer_scope": {
              "type": "string",
              "const": "same_property_profile_aggregation_current_window_leave_one_out"
            },
            "sort": {
              "type": "string",
              "const": "primary_reason_then_severity_desc_then_exact_key_C"
            },
            "threshold_mode": {
              "type": "string",
              "enum": [
                "scaled",
                "fixed"
              ]
            },
            "overridden": {
              "maxItems": 8,
              "type": "array",
              "items": {
                "type": "string",
                "enum": [
                  "min_impressions",
                  "decline_min_clicks",
                  "decline_max_percent",
                  "peer_min_count",
                  "peer_min_impressions",
                  "ctr_max_ratio",
                  "visibility_min_improvement",
                  "visibility_max_current_position"
                ]
              }
            },
            "scaling_basis": {
              "anyOf": [
                {
                  "type": "object",
                  "properties": {
                    "current_window_entity_impressions": {
                      "type": "integer",
                      "minimum": 0,
                      "maximum": 9007199254740991
                    }
                  },
                  "required": [
                    "current_window_entity_impressions"
                  ],
                  "additionalProperties": false
                },
                {
                  "type": "null"
                }
              ]
            }
          },
          "required": [
            "version",
            "min_impressions",
            "decline_min_clicks",
            "decline_max_delta",
            "decline_max_percent",
            "block_days",
            "persistence_min_days",
            "persistence_min_blocks",
            "block_decline_max_percent",
            "persistence_min_fraction",
            "position_bands",
            "peer_min_count",
            "peer_min_impressions",
            "ctr_max_ratio",
            "visibility_min_improvement",
            "visibility_max_current_position",
            "reason_order",
            "peer_scope",
            "sort",
            "threshold_mode",
            "overridden",
            "scaling_basis"
          ],
          "additionalProperties": false
        },
        "status": {
          "type": "string",
          "enum": [
            "ok",
            "ok_with_warnings",
            "insufficient_data",
            "incompatible_aggregation",
            "scan_budget_exceeded"
          ]
        },
        "total_candidate_entities": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "requested_limit": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50
        },
        "returned_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "omitted_count": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "byte_limited": {
          "type": "boolean"
        },
        "candidates": {
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              },
              "baseline": {
                "type": "object",
                "properties": {
                  "observation": {
                    "type": "string",
                    "enum": [
                      "observed",
                      "not_observed"
                    ]
                  },
                  "entity_observed_days": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "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
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "position": {
                    "anyOf": [
                      {
                        "type": "number",
                        "minimum": 0
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "observation",
                  "entity_observed_days",
                  "clicks",
                  "impressions",
                  "ctr",
                  "position"
                ],
                "additionalProperties": false
              },
              "current": {
                "type": "object",
                "properties": {
                  "observation": {
                    "type": "string",
                    "enum": [
                      "observed",
                      "not_observed"
                    ]
                  },
                  "entity_observed_days": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "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
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "position": {
                    "anyOf": [
                      {
                        "type": "number",
                        "minimum": 0
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                },
                "required": [
                  "observation",
                  "entity_observed_days",
                  "clicks",
                  "impressions",
                  "ctr",
                  "position"
                ],
                "additionalProperties": false
              },
              "primary_reason": {
                "type": "string",
                "enum": [
                  "clicks_declined",
                  "high_impressions_low_ctr",
                  "visibility_improved"
                ]
              },
              "reasons": {
                "minItems": 1,
                "maxItems": 3,
                "type": "array",
                "items": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "reason": {
                          "type": "string",
                          "const": "clicks_declined"
                        },
                        "click_delta": {
                          "type": "integer",
                          "minimum": -9007199254740991,
                          "maximum": 9007199254740991
                        },
                        "clicks_percent": {
                          "type": "number"
                        },
                        "persistence": {
                          "type": "string",
                          "enum": [
                            "not_assessed_short_window",
                            "persistent_observed_decline"
                          ]
                        },
                        "planned_blocks": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "eligible_blocks": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "declined_blocks": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "trailing_days": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "blocks": {
                          "maxItems": 12,
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "index": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 9007199254740991
                              },
                              "baseline": {
                                "type": "object",
                                "properties": {
                                  "observation": {
                                    "type": "string",
                                    "enum": [
                                      "observed",
                                      "not_observed"
                                    ]
                                  },
                                  "entity_observed_days": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 9007199254740991
                                  },
                                  "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
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "position": {
                                    "anyOf": [
                                      {
                                        "type": "number",
                                        "minimum": 0
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "required": [
                                  "observation",
                                  "entity_observed_days",
                                  "clicks",
                                  "impressions",
                                  "ctr",
                                  "position"
                                ],
                                "additionalProperties": false
                              },
                              "current": {
                                "type": "object",
                                "properties": {
                                  "observation": {
                                    "type": "string",
                                    "enum": [
                                      "observed",
                                      "not_observed"
                                    ]
                                  },
                                  "entity_observed_days": {
                                    "type": "integer",
                                    "minimum": 0,
                                    "maximum": 9007199254740991
                                  },
                                  "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
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  },
                                  "position": {
                                    "anyOf": [
                                      {
                                        "type": "number",
                                        "minimum": 0
                                      },
                                      {
                                        "type": "null"
                                      }
                                    ]
                                  }
                                },
                                "required": [
                                  "observation",
                                  "entity_observed_days",
                                  "clicks",
                                  "impressions",
                                  "ctr",
                                  "position"
                                ],
                                "additionalProperties": false
                              },
                              "eligible": {
                                "type": "boolean"
                              },
                              "clicks_percent": {
                                "type": [
                                  "number",
                                  "null"
                                ]
                              },
                              "declined": {
                                "type": "boolean"
                              }
                            },
                            "required": [
                              "index",
                              "baseline",
                              "current",
                              "eligible",
                              "clicks_percent",
                              "declined"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "reason",
                        "click_delta",
                        "clicks_percent",
                        "persistence",
                        "planned_blocks",
                        "eligible_blocks",
                        "declined_blocks",
                        "trailing_days",
                        "blocks"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "reason": {
                          "type": "string",
                          "const": "high_impressions_low_ctr"
                        },
                        "band": {
                          "type": "array",
                          "items": [
                            {
                              "type": "number"
                            },
                            {
                              "type": [
                                "number",
                                "null"
                              ]
                            }
                          ],
                          "additionalItems": false,
                          "minItems": 2,
                          "maxItems": 2
                        },
                        "peer_count": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "peer_impressions": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "peer_clicks": {
                          "type": "integer",
                          "minimum": 0,
                          "maximum": 9007199254740991
                        },
                        "baseline_ctr": {
                          "type": "number",
                          "exclusiveMinimum": 0
                        },
                        "gap_percentage_points": {
                          "type": "number",
                          "minimum": 0
                        }
                      },
                      "required": [
                        "reason",
                        "band",
                        "peer_count",
                        "peer_impressions",
                        "peer_clicks",
                        "baseline_ctr",
                        "gap_percentage_points"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "reason": {
                          "type": "string",
                          "const": "visibility_improved"
                        },
                        "position_improvement": {
                          "type": "number"
                        }
                      },
                      "required": [
                        "reason",
                        "position_improvement"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              },
              "sitemap_membership": {
                "anyOf": [
                  {
                    "type": "string",
                    "enum": [
                      "listed",
                      "variant_listed",
                      "not_listed"
                    ]
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "key",
              "baseline",
              "current",
              "primary_reason",
              "reasons"
            ],
            "additionalProperties": false
          }
        },
        "scan_policy": {
          "type": "object",
          "properties": {
            "max_rows": {
              "type": "number",
              "const": 6000000
            },
            "statement_timeout_ms": {
              "type": "number",
              "const": 5000
            }
          },
          "required": [
            "max_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._:-]+$"
          }
        },
        "sitemap": {
          "type": "object",
          "properties": {
            "version": {
              "type": "string",
              "const": "1.0.0"
            },
            "status": {
              "type": "string",
              "enum": [
                "ready",
                "no_sitemap_snapshot",
                "not_applicable"
              ]
            },
            "snapshot_day": {
              "anyOf": [
                {
                  "type": "string",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                },
                {
                  "type": "null"
                }
              ]
            },
            "source": {
              "anyOf": [
                {
                  "type": "string",
                  "enum": [
                    "google",
                    "fixture"
                  ]
                },
                {
                  "type": "null"
                }
              ]
            },
            "caveats": {
              "maxItems": 5,
              "type": "array",
              "items": {
                "type": "string",
                "maxLength": 300
              }
            }
          },
          "required": [
            "version",
            "status",
            "snapshot_day",
            "source",
            "caveats"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "kind",
        "schema_version",
        "analysis_version",
        "policy_version",
        "property_id",
        "entity",
        "source",
        "windows",
        "filters",
        "source_revisions",
        "coverage",
        "aggregation",
        "selection_policy",
        "status",
        "total_candidate_entities",
        "requested_limit",
        "returned_count",
        "omitted_count",
        "byte_limited",
        "candidates",
        "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
    }
  ]
}
```