---
title: "A site's distinct Search Console queries per day"
method: GET
path: "/v1/sites/{site}/search/query-counts"
tags: ["gsc"]
---

# A site's distinct Search Console queries per day

`GET /v1/sites/{site}/search/query-counts`

## Request

- Base URL: `https://frontshelf.io/api`
- URL: `https://frontshelf.io/api/v1/sites/{site}/search/query-counts`
- Auth: HTTP bearer

Per day over `range`, how many distinct queries a site's Search Console property showed for, how many of them earned a click, and how many ranked 1 to 3, 4 to 10, 11 to 20 and 21+ (`bands`), from the data Frontshelf stores; `filter` narrows the queries counted. The counts are of Google's observed rows, so they are floors, and `coverage` says which days are missing, provisional or capped: a missing day is absent, never 0. Free (query_counts). Next: gsc_table_get with dimension query for the queries themselves.

## Path parameters

- `site` string, required: Site ID (site_…), origin (https://example.com), or bare domain, resolved server-side; the response carries the canonical ID.

## Query parameters

- `source_id` string: One of the site's Search Console properties (ssrc_…, from gsc_sources_list). Omit for the site's primary property.
- `type` 'web' | 'image' | 'video' | 'news' | 'discover' | 'googleNews': The Google search surface: web (default), image, video, news, discover or googleNews. Discover and Google News have no query dimension and no position.
- `range` union: The dates, as Pacific calendar days: a word (yesterday, 7d, 14d, 28d, 3m, 6m, 12m, 16m, this_month, last_month, this_quarter, last_quarter, ytd, all; last:<days>; <start>..<end>) or the object it stands for ({preset}, {last_days: n}, {start, end} as YYYY-MM-DD). Default 28d.
  - string
  - object
    - `preset` 'yesterday' | '7d' | '14d' | '28d' | '3m' | '6m' | '12m' | '16m' | 'this_month' | 'last_month' | 'this_quarter' | 'last_quarter' | 'ytd' | 'all', required
  - object
    - `last_days` integer, required
  - object
    - `start` string, required
    - `end` string, required
- `compare` union: What to compare against: none (default), previous (the same length before), year (a year earlier), year-weekdays (364 days earlier, weekdays matched) or <start>..<end>; or the object: {kind: none | previous}, {kind: year, match_weekdays}, {kind: custom, start, end}.
  - string
  - object
    - `kind` 'none' | 'previous', required
  - object
    - `kind` 'year', required
    - `match_weekdays` boolean, required
  - object
    - `kind` 'custom', required
    - `start` string, required
    - `end` string, required
- `filter` object: Narrow the rows: query and page as lists of {op: contains | equals | regex | not_contains | not_equals | not_regex, values} (values ORed, conditions ANDed, RE2 patterns); country {mode: include | exclude, codes} as lower-case ISO 3166-1 alpha-3; device {mode, devices: desktop | mobile | tablet}; segments [{id, mode}]; brand: branded | non_branded (needs brand terms); presets: question, long_tail; daily_position_max. Default: nothing narrowed.
  - `query` object[]
    - `op` 'contains' | 'equals' | 'regex' | 'not_contains' | 'not_equals' | 'not_regex', required
    - `values` string[], required
  - `page` object[]
    - `op` 'contains' | 'equals' | 'regex' | 'not_contains' | 'not_equals' | 'not_regex', required
    - `values` string[], required
  - `country` object
    - `mode` 'include' | 'exclude', required
    - `codes` string[], required
  - `device` object
    - `mode` 'include' | 'exclude', required
    - `devices` string[], required
  - `segments` object[]
    - `id` string, required
    - `mode` 'include' | 'exclude', required
  - `brand` 'branded' | 'non_branded'
  - `presets` string[]
  - `daily_position_max` number
- `saved_filter_id` string: A saved filter (ssf_…, from gsc_filters_list) applied on top of `filter`; a cursor read under it expires when the filter is edited.

## Response `200`

A site's distinct Search Console queries per day

- object
  - `summary` string, required: The answer in one or two sentences, with the numbers it rests on.
  - `warnings` string[], required: What limits this answer (a cap, a read that was cut short). Empty when nothing does.
  - `next_actions` object[], required: What to call next, best first. Follow them.
    - `capability` string, required: What to call next: a capability.
    - `arguments` object, required: Its arguments, complete; pass them as they are.
    - `instruction` string, required: What to do, written to you.
  - `provenance` object, required
    - `crawl_seq` integer, nullable, required: The crawl the answer was read from; null when the site has none yet.
    - `data_freshness` string, required: When that crawl finished (ISO 8601) or `no completed crawl`; for a read of one committed crawl, `committed crawl (immutable snapshot)`, or `not committed (<reason>)` when nothing committed answered.
  - `site_id` string, required: The site's canonical id.
  - `source_id` string, required: The property the figures are from (ssrc_…).
  - `days` object[], required
    - `date` string, required
    - `total` integer, required
    - `with_clicks` integer, required
    - `bands` object, required
      - `1-3` integer, required
      - `4-10` integer, required
      - `11-20` integer, required
      - `21+` integer, required
    - `provisional` boolean, required
  - `coverage` object, required: What the figures cover: the dates, the basis, the missing and provisional days, the capped days, the snapshot.
    - `start` string, required: A Pacific calendar day, YYYY-MM-DD.
    - `end` string, required: A Pacific calendar day, YYYY-MM-DD.
    - `grain` 'totals' | 'country_device' | 'query' | 'page' | 'query_page', required
    - `cut` 'all' | 'coarse' | 'geo', required
    - `basis` 'exact' | 'observed', required: `exact`: unfiltered totals; `observed`: Google's listed top rows (any query or page filter), a floor.
    - `aggregation` string, required
    - `snapshot_seq` string, required: The publication the read was fixed at.
    - `final_through` string, nullable, required: The last final day; null before the first.
    - `provisional_days` string[], required: Days Google may still restate.
    - `gaps` object[], required: Days with no figures and why: absent, never 0.
      - `start` string, required: A Pacific calendar day, YYYY-MM-DD.
      - `end` string, required: A Pacific calendar day, YYYY-MM-DD.
      - `reason` 'before_history' | 'not_fetched' | 'unrecoverable' | 'not_final', required
    - `capped_days` integer, required: Days Google listed only its top rows on: the detail is a floor.
    - `unsupported` boolean, required: True: Google does not answer this combination, so there are no figures; nothing was measured as 0.

## Other responses

- `400`: SEARCH_SPEC_INVALID, VALIDATION_FAILED
- `401`: UNAUTHENTICATED
- `402`: BILLING_REQUIRED
- `403`: SCOPE_DENIED
- `404`: SITE_NOT_FOUND, NOT_FOUND
- `409`: AMBIGUOUS_SITE, SEARCH_NOT_CONNECTED, AGENT_STOPPED
- `503`: DEPENDENCY_UNAVAILABLE

---

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