Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

GSC Performance History

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>'

Returns time-series points for selected GSC performance metrics over the filtered dataset. The series follows the same filters as the summary, so it charts the filtered subset rather than the whole project.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “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

Section titled “Responses”

200

Section titled “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

The series itself, one point per period.

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

Section titled “401”

Missing or invalid API key

Media typeapplication/json

Returned as INVALID_API_KEY when the key is missing or unknown, and as REVOKED_API_KEY when the key exists but was revoked — the latter needs a new key.

object
error
required
object
code
required
string
Allowed values: VALIDATION_ERROR BAD_REQUEST PROJECT_NOT_FOUND SEGMENT_NOT_FOUND ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key."
  }
}

403

Section titled “403”

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

Media typeapplication/json

Returned as MISSING_PUBLIC_API_ACCESS when the account has no active API entitlement, and as ACCESS_DENIED 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "MISSING_PUBLIC_API_ACCESS",
    "message": "API access is not available: the account has no active API entitlement."
  }
}

404

Section titled “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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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

Section titled “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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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

Section titled “422”

Validation error, invalid date range or invalid filter

Media typeapplication/json

Rejected query parameters. error.code is VALIDATION_ERROR for parameter validation (including a query parameter the endpoint does not accept), or INVALID_DATE_RANGE / INVALID_FILTER / INVALID_EVENT_TYPE / UNSUPPORTED_FILTER / UNSUPPORTED_DIMENSION / UNSUPPORTED_METRIC / 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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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

Section titled “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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC 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

Section titled “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 ACCESS_DENIED CRAWL_IN_PROGRESS NOT_FOUND UPSTREAM_ERROR INVALID_API_KEY REVOKED_API_KEY RATE_LIMIT_EXCEEDED MISSING_PUBLIC_API_ACCESS 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 UNSUPPORTED_METRIC SEGMENT_FILTER_UNSUPPORTED UNSUPPORTED_SCOPE AI_OVERVIEW_DATA_UNAVAILABLE PROMPT_DATA_UNAVAILABLE
message
required
string
Example
{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error."
  }
}