API docs v1
GET /v1/brands/{brand_id}/search-console/performance

Read Search Console performance

scope read:analytics cost 2 RU

What the brand's site earned in Google: clicks, impressions, CTR and average position, split by dimension (query, page, country, device or date). totals is the site-wide total for the window (totals.key says whether it is the site's own figure or the sum of the rows). CTR is a percentage. dimension=query reads every query Search Console exposes for the window live from Google (kept five minutes), most clicks first, paged with limit (1-1000, default 1000) and offset; total counts them all and has_more says another page follows. On a very large site the first read of a window can take a minute or more; calls for the same window share that read, and it finishes even when the caller gives up, so a retry a minute later is served from the kept copy. The other dimensions come whole from the stored snapshot: the top 1000 pages, 300 countries, every device, one row per day. Pass query with dimension=date to get one query's history day by day, read live from Google; totals stays the site's, not that query's.

With dimension=query: search keeps the queries holding that text (case and spacing ignored) and order_by (query, clicks, impressions, ctr or position) with order_dir (asc or desc, default desc) sorts them, ties broken by the query. country (the full English name, e.g. United States) reads dimension=query or dimension=page in that country only, live from Google and kept five minutes per window and country like the queries; totals stays the site's.

engine=bing reads the same numbers from the brand's Bing Webmaster Tools site instead (connected in the app): dimension query, page or date, every query paged with limit and offset, every page whole; query, search, order_by and country are Google only. Bing is read again every six hours. Without a Bing site the call answers integration_not_connected with the page to connect it.

start_date and end_date are YYYY-MM-DD; they default to the last 28 days up to today. Search Console lags two to three days: data_through says how far it is complete.

Path parameters

Query parameters

  • engine string (enum) optional

    google (Search Console, the default) or bing (Bing Webmaster Tools).

    one of google, bing · default: google

  • dimension string (enum) optional

    What each row stands for.

    one of query, page, country, device, date · default: query

  • query string optional

    With dimension=date, the query whose history to return.

  • order_by string optional

    With dimension=query, the column to sort by.

  • order_dir string (enum) optional

    Sort direction. Default desc.

    one of asc, desc · default: desc

  • country string optional

    With dimension=query or page, only searches from this country (full English name).

  • start_date string optional

    First day of the window (YYYY-MM-DD).

  • end_date string optional

    Last day of the window (YYYY-MM-DD).

  • limit integer optional

    With dimension=query, or a country, rows per page.

    default: 1000

  • offset integer optional

    With dimension=query, or a country, rows to skip.

    default: 0

  • dry_run boolean optional

    Preview the call without executing it. Runs auth, scope, eligibility and body validation, then returns 200 with a dry_run object reporting the request-unit and credit cost plus a non-consuming quota snapshot. Nothing is debited, reserved, dispatched or mutated. An invalid body still returns 422.

    default: false

Responses

Read Search Console performance application/json
Type: SearchPerformance
  • data array of SearchRow required

    Rows for the dimension, most clicks first (by day for date). query is every query Search Console exposes for the window, a page at a time; the other dimensions come whole from the stored snapshot: the top 1000 pages, 300 countries, every device, one row per day.

  • dimension enum required

    What each row stands for.

  • total integer required

    Rows the dimension holds for the window, across every page.

    min: 0

  • data_through string (nullable) nullable

    Last day Search Console has complete data for; it lags two to three days.

  • date_range_end string (nullable) nullable
  • date_range_start string (nullable) nullable
  • engine enum

    google (Search Console) or bing (Bing Webmaster Tools), as asked.

    default: `google`

  • has_more boolean

    With dimension=query, true when more queries follow: raise offset.

    default: `false`

  • last_sync_at string (nullable) nullable

    When Google was last read for this window; null when nothing is stored for it. Refresh when it is null or old.

    format: `date-time`

  • object string

    default: `search_performance`

  • query string (nullable) nullable

    Set when the rows are one query's history by date.

  • site_url string (nullable) nullable

    The connected Search Console site, or the Bing Webmaster Tools site with bing.

  • totals SearchRow (nullable) nullable

    Totals for the window. key is site when they come from a site-wide query, and sum_of_rows when only the rows were stored. With query they stay the site's, not that query's.

Request validation failed application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Missing or invalid credentials application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid credentials"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
You do not have permission to access this resource application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource not found application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Resource conflict application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "conflict",
    "message": "Resource conflict"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Per-minute rate limit exceeded application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Per-minute rate limit exceeded"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
An unexpected error occurred application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}
Service temporarily unavailable, please retry application/json
Type: ApiError
  • error object required
    Show fields
    • code string required

      Stable machine-readable error code from the catalog.

    • message string required

      Human-readable description suitable for logging.

    • details object

      Optional, code-specific context (e.g. errors array for validation_error, retry_after for service_unavailable). Shape depends on error.code; treat as opaque otherwise.

      Show fields

      Empty object (no properties).

  • request_id string

    Server-generated correlation id for the request. Mirrors the X-Correlation-ID response header. Include this when contacting support.

    format: `uuid`

Example response 
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable, please retry"
  },
  "request_id": "9f6c4e8a-1d3b-4c8b-9f1e-7a3b1c2d3e4f"
}