---
title: "Query Google Search Console performance"
method: POST
path: "/analytics/search-console/query"
tags: ["Analytics"]
---

# Query Google Search Console performance

`POST /analytics/search-console/query`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/analytics/search-console/query`
- Auth: HTTP bearer

Runs a live, finalized Search Analytics query against the Board’s connected Google Search Console property. Uses Google’s request and row shape while enforcing the Board’s stored reporting coverage. Results are top rows and are not exhaustive.

## Request body

- object
  - `startDate` string, required
  - `endDate` string, required
  - `dimensions` string[]
  - `type` 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews'
  - `dimensionFilterGroups` object[]
    - `groupType` 'and', required
    - `filters` object[], required
      - `dimension` 'country' | 'device' | 'page' | 'query' | 'searchAppearance', required
      - `operator` 'contains' | 'equals' | 'notContains' | 'notEquals' | 'includingRegex' | 'excludingRegex', required
      - `expression` string, required
  - `aggregationType` 'auto' | 'byPage' | 'byProperty'
  - `rowLimit` integer
  - `startRow` integer
  - `dataState` 'final'

## Response `200`

Live finalized Search Console performance rows.

- SearchConsoleQueryResponse
  - `object` 'search_console_query', required
  - `rows` object[], required
    - `keys` string[]
    - `clicks` number
    - `impressions` number
    - `ctr` number
    - `position` number
  - `responseAggregationType` string
  - `metadata` object
  - `cavuno` object, required
    - `coverage` object, required
      - `mode` 'board_hosts' | 'whole_property', required
      - `hostnames` string[], required
    - `dataState` 'final', required
    - `dataTimezone` 'America/Los_Angeles', required
    - `latestObservedDate` string
    - `exhaustive` false, required

## Other responses

- `409`: Search Console is not connected or access was lost.
- `429`: Google Search Console quota was reached.
- `502`: Google rejected the validated request.
- `503`: Google Search Console is unavailable.

## Changes

- **2026-10-19** `c34152c38176`: 4 info
  - added the optional property `error/upgrade` to the response with the `409` status
  - added the optional property `error/upgrade` to the response with the `429` status
  - added the optional property `error/upgrade` to the response with the `502` status
  - added the optional property `error/upgrade` to the response with the `503` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/analytics/search-console/query/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)