Time-series points for selected GSC metrics over the filtered dataset.

GET

/api/v1/gsc-insights/performance-history

curl --request GET \
  --url 'https://sitechecker.pro/api/v1/gsc-insights/performance-history?project_id=12345&date_from=2026-02-19&date_to=2026-05-19&compare_from=2026-01-01&compare_to=2026-01-31&history_grouping=daily&metrics=clicks%2Cimpressions&group_by=none&segment_id=all_pages&device=desktop&country=usa&brand_type=all&filters=%7B%22join%22%3A%22and%22%2C%22rules%22%3A%5B%7B%22field%22%3A%22keyword%22%2C%22operator%22%3A%22regex%22%2C%22value%22%3A%22seo%7Caudit%22%7D%2C%7B%22field%22%3A%22clicks%22%2C%22operator%22%3A%22gte%22%2C%22value%22%3A100%7D%5D%7D' \
  --header 'Authorization: Bearer <token>'

• Production

Authorizations

• bearerAuth

Parameters

Query Parameters

project_id

required

integer

Example

12345

Project ID.

date_from

required

string format: date

Example

2026-02-19

Start of the monitoring period (inclusive), ISO date (UTC).

date_to

required

string format: date

Example

2026-05-19

End of the monitoring period (inclusive), ISO date (UTC).

compare_from

string format: date

Example

2026-01-01

Start of the manual comparison period (inclusive). Must be passed together with compare_to; the response switches to nested current/previous/change blocks.

compare_to

string format: date

Example

2026-01-31

End of the manual comparison period (inclusive). Must be passed together with compare_from.

history_grouping

string

default: daily

Allowed values: daily weekly monthly

Time bucket for history points.

metrics

string

Example

clicks,impressions

Comma-separated metric list. Default: clicks,impressions,ctr,average_position.

group_by

string

default: none

Allowed values: none brand

Brand splits the series into brand/non-brand (Brand vs Non-brand history).

segment_id

string

Example

all_pages

Optional segment scope filter.

device

string

Allowed values: desktop mobile tablet

Filter the underlying GSC rows by device before aggregation.

country

string

Example

usa

Filter the underlying GSC rows by country (ISO-3166-1 alpha-3, lowercase) before aggregation. Use values from gsc_insights_filter_values.

brand_type

string

default: all

Allowed values: all brand non_brand

Brand/non-brand keyword filter based on the brand rules configured in Settings. Requires brand_settings_configured=true.

keyword

string

Keyword text search applied to the underlying rows (filtered graph).

page

string

Page URL text search applied to the underlying rows (filtered graph).

filters

string

Example

{"join":"and","rules":[{"field":"keyword","operator":"regex","value":"seo|audit"},{"field":"clicks","operator":"gte","value":100}]}

Advanced filter object (URL-encoded JSON): {“join”:“and|or”,“rules”:[{“field”:…,“operator”:…,“value”:…}, {“join”:“or”,“rules”:[…]}]}. Text fields (keyword, page_url, top_ranking_keyword, top_ranking_page): equals, not_equals, contains, not_contains, starts_with, ends_with, regex, not_regex, in, not_in. Numeric fields (clicks, impressions, ctr, average_position): equals, gte, lte, between, plus gt/lt for integer fields. Enum fields (country, device): equals, in. Nested groups are supported one level deep; rules inside one “or” group must target the same text field. Simple query params are AND-joined with this object.

Responses

200

History points (or per-brand series with group_by=brand)

Media typeapplication/json

object

data

History payload: points (+ previous_points with compare; series[] per brand type with group_by=brand). Point keys follow the requested metrics.

object

points

Array<object>

object

date

Point date / period start.

string format: date

clicks

Clicks.

integer

impressions

Impressions.

integer

ctr

CTR.

number format: float

nullable

average_position

Average position.

number format: float

nullable

previous_points

Comparison overlay points; present when compare params are used.

Array<object>

nullable

object

series

Per-series points when group_by=brand splits the data into brand / non-brand.

Array<object>

nullable

object

meta

Standard GSC Insights meta block: request scope echo, source availability and data freshness. Extended per endpoint (history_grouping, resolved_compare_*, ga4_channel_scope…).

object

project_id

Project ID.

integer

date_from

Selected period start.

string format: date

date_to

Selected period end.

string format: date

compare_from

Optional comparison period start.

string format: date

nullable

compare_to

Optional comparison period end.

string format: date

nullable

source_status

Source connection/data availability statuses keyed by source (e.g. gsc, ga4).

object

key

additional properties

string

data_freshness

Latest data date used per source (e.g. gsc_date, ga4_date).

object

key

additional properties

string

nullable

Example

{
  "data": {
    "points": [
      {
        "date": "2026-05-01",
        "clicks": 120,
        "impressions": 3050,
        "ctr": 3.93,
        "average_position": 12.4
      }
    ]
  },
  "meta": {
    "project_id": 12345,
    "date_from": "2026-05-01",
    "date_to": "2026-05-31",
    "source_status": {
      "gsc": "connected",
      "ga4": "not_connected"
    },
    "data_freshness": {
      "gsc_date": "2026-06-30",
      "ga4_date": "2026-07-02"
    }
  }
}

401

Missing or invalid API key

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

403

No active API entitlement for the account, or the project belongs to another account

Media typeapplication/json

Returned as api_access_denied when the account has no active API entitlement, and as forbidden when the requested project belongs to another account.

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "api_access_denied",
    "message": "API access is not available: the account has no active API entitlement."
  }
}

404

Project not found

Media typeapplication/json

The exact missing resource is in error.code: project_not_found, segment_not_found, crawl_not_found, keyword_not_found, opportunity_not_found, snapshot_unavailable or not_found.

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "project_not_found",
    "message": "Project not found."
  }
}

409

Google Search Console is not connected

Media typeapplication/json

Also returned as site_audit_data_unavailable on endpoints that join Site Audit page content.

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "gsc_not_connected",
    "message": "Google Search Console is not connected for this project."
  }
}

422

Validation error, invalid date range or invalid filter

Media typeapplication/json

Rejected query parameters. error.code is validation_error for parameter validation, or invalid_date_range / invalid_filter / invalid_event_type / unsupported_filter / unsupported_dimension / unsupported_scope / segment_filter_unsupported for module-specific rules.

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "validation_error",
    "message": "project_id is required."
  }
}

429

Rate limit exceeded — retry after the interval in the Retry-After header

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again later."
  }
}

500

Internal server error

Media typeapplication/json

object

error

required

object

code

required

string

Allowed values: validation_error bad_request project_not_found segment_not_found forbidden crawl_in_progress not_found upstream_error unauthorized rate_limit_exceeded api_access_denied internal_error crawl_not_found invalid_date_range invalid_filter invalid_event_type keyword_not_found opportunity_not_found snapshot_unavailable gsc_not_connected ga4_not_connected site_audit_data_unavailable ga4_data_unavailable unsupported_filter unsupported_dimension segment_filter_unsupported unsupported_scope ai_overview_data_unavailable prompt_data_unavailable

message

required

string

Example

{
  "error": {
    "code": "internal_error",
    "message": "Internal server error."
  }
}