> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seomator.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Search Console clicks, impressions, CTR and position

> Groups by `dimensions` (query, page, country, device, searchAppearance, date) over `startDate`–`endDate` (default: the last 28 final days, ending 3 days ago). `totals` cover every row; page with `limit` and `nextCursor`.

Reads only the project country unless `country` is `all`. 409 when Search Console is not connected or access was lost; 503 when Google does not answer. Answers are cached a day (an hour with `fresh` and for inspections).



## OpenAPI

````yaml https://api.seomator.com/openapi.json post /v1/projects/{id}/gsc/query
openapi: 3.1.0
info:
  title: SEOmator API
  version: 0.1.0
servers:
  - url: https://api.seomator.com
security: []
paths:
  /v1/projects/{id}/gsc/query:
    post:
      tags:
        - search console
      summary: Query Search Console clicks, impressions, CTR and position
      description: >-
        Groups by `dimensions` (query, page, country, device, searchAppearance,
        date) over `startDate`–`endDate` (default: the last 28 final days,
        ending 3 days ago). `totals` cover every row; page with `limit` and
        `nextCursor`.


        Reads only the project country unless `country` is `all`. 409 when
        Search Console is not connected or access was lost; 503 when Google does
        not answer. Answers are cached a day (an hour with `fresh` and for
        inspections).
      parameters:
        - schema:
            type: string
            description: Project id (proj_…) or slug (the domain with dots as dashes).
          required: true
          description: Project id (proj_…) or slug (the domain with dots as dashes).
          name: id
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dimensions:
                  type: array
                  items:
                    type: string
                    enum:
                      - query
                      - page
                      - country
                      - device
                      - searchAppearance
                      - date
                  maxItems: 4
                  default:
                    - query
                  description: Group rows by these; an empty list gives the totals only.
                startDate:
                  type: string
                  format: date
                  description: >-
                    First day (YYYY-MM-DD, Pacific time). Defaults to 28 days
                    before endDate.
                endDate:
                  type: string
                  format: date
                  description: >-
                    Last day (YYYY-MM-DD). Defaults to 3 days ago, the last
                    final day.
                country:
                  type: string
                  description: >-
                    ISO 3166-1 alpha-2 country, e.g. tr. Defaults to the project
                    country; all reads every country.
                filters:
                  type: array
                  items:
                    type: object
                    properties:
                      dimension:
                        type: string
                        enum:
                          - query
                          - page
                          - country
                          - device
                          - searchAppearance
                      operator:
                        type: string
                        enum:
                          - equals
                          - notEquals
                          - contains
                          - notContains
                          - includingRegex
                          - excludingRegex
                        default: contains
                      expression:
                        type: string
                        minLength: 1
                        maxLength: 4096
                        description: >-
                          Text to match; a country is an alpha-2 code, a device
                          DESKTOP, MOBILE or TABLET, a regex uses RE2 syntax.
                    required:
                      - dimension
                      - expression
                  maxItems: 10
                  default: []
                type:
                  type: string
                  enum:
                    - web
                    - image
                    - video
                    - news
                    - discover
                    - googleNews
                  default: web
                fresh:
                  type: boolean
                  default: false
                  description: Include the last 2–3 days, which Google is still counting.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 1000
                  default: 100
                  description: Rows per page, most clicks first, as Google orders them.
                cursor:
                  type: string
      responses:
        '200':
          description: Rows
          content:
            application/json:
              schema:
                type: object
                properties:
                  property:
                    type: string
                  country:
                    type:
                      - string
                      - 'null'
                  type:
                    type: string
                    enum:
                      - web
                      - image
                      - video
                      - news
                      - discover
                      - googleNews
                  period:
                    type: object
                    properties:
                      start:
                        type: string
                      end:
                        type: string
                    required:
                      - start
                      - end
                    additionalProperties: {}
                  totals:
                    type: object
                    properties:
                      clicks:
                        type: number
                      impressions:
                        type: number
                      ctr:
                        type: number
                      position:
                        type: number
                    required:
                      - clicks
                      - impressions
                      - ctr
                      - position
                    additionalProperties: {}
                  rows:
                    type: array
                    items:
                      type: object
                      properties:
                        query:
                          type: string
                        page:
                          type: string
                        country:
                          type: string
                        device:
                          type: string
                        searchAppearance:
                          type: string
                        date:
                          type: string
                        clicks:
                          type: number
                        impressions:
                          type: number
                        ctr:
                          type: number
                        position:
                          type: number
                      required:
                        - clicks
                        - impressions
                        - ctr
                        - position
                      additionalProperties: {}
                  nextCursor:
                    type:
                      - string
                      - 'null'
                required:
                  - property
                  - country
                  - type
                  - period
                  - totals
                  - rows
                  - nextCursor
                additionalProperties: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Try again later
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - bad_request
                - unauthorized
                - insufficient_credits
                - plan_limit
                - forbidden
                - not_found
                - conflict
                - rate_limit_exceeded
                - internal_server_error
                - service_unavailable
            message:
              type: string
            requestId:
              type: string
          required:
            - code
            - message
      required:
        - error
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

## Related topics

- [MCP server: connect Claude, ChatGPT and more](https://docs.seomator.com/mcp/setup.md)
- [AI SEO Agent: ask about your AI visibility](https://docs.seomator.com/agent/overview.md)
- [Projects: set up, track and manage a site](https://docs.seomator.com/getting-started/projects.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.