GSC Keyword Gap Pages

GET

/api/v1/gsc-insights/keyword-gap-pages

curl --request GET \
  --url 'https://sitechecker.pro/api/v1/gsc-insights/keyword-gap-pages?project_id=12345&order_by=page_clicks_desc&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

• Production

Returns page-level Keyword Gap summary with GSC metrics, gap metrics, and content usage flags. Pages the crawler has not reached come back with null gap metrics and usage flags rather than zeros. This report takes no comparison period.

Authorizations

• bearerAuth

Parameters

Query Parameters

project_id

required

integer

Example

12345

Project ID.

date_from

string format: date

Start of the GSC window (inclusive). Default: last 30 days of final GSC data (UI parity).

date_to

string format: date

End of the GSC window (inclusive).

page

string

Page URL text search.

order_by

string

Example

page_clicks_desc

Sort as _asc|_desc: page_url, top_keyword, page_clicks, page_impressions, page_average_position, page_ctr.

limit

integer

default: 50 >= 1 <= 100

Page size.

offset

integer

0

Pagination offset.

Responses

200

Keyword Gap page rows (lost_clicks = max(keyword_impressions * 0.2 - keyword_clicks, 0); count/percent = keyword occurrences in the page text)

Media typeapplication/json

object

data

Array<object>

Keyword Gap page row. lost_clicks = max(keyword_impressions * 0.2 - keyword_clicks, 0); count/percent = top keyword occurrences in the page text (crawler). Null usage flags mean no content data for the page (not crawled).

object

page_url

Page URL.

string

top_keyword

Top keyword for the page.

string

nullable

page_clicks

GSC page clicks.

integer

nullable

page_impressions

GSC page impressions.

integer

nullable

page_ctr

GSC page CTR.

number format: float

nullable

page_average_position

GSC page average position.

number format: float

nullable

keyword_clicks

GSC clicks from the top/selected keyword.

integer

nullable

keyword_impressions

GSC impressions for the top/selected keyword.

integer

nullable

keyword_position

GSC average position for the top/selected keyword.

number format: float

nullable

lost_clicks

Estimated lost clicks: max(keyword_impressions * 0.2 - keyword_clicks, 0).

number format: float

nullable

count

Top keyword occurrences in the page text (crawler).

integer

nullable

percent

Top keyword occurrence percentage in the page text (crawler).

number format: float

nullable

used_in_title

Whether the top keyword is used in the title.

boolean

nullable

used_in_description

Whether used in the meta description.

boolean

nullable

used_in_h1

Whether used in H1.

boolean

nullable

used_in_h2_h6

Whether used in H2-H6.

boolean

nullable

used_in_alt_tags

Whether used in image alt tags.

boolean

nullable

meta

GSC Insights meta block for list endpoints: scope echo + pagination (total/limit/offset).

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

total

Reusable OpenAPI response schemas for the Public REST API: the error/meta envelope and one item schema per resource. Property names come from the Field registry so the documented contract and the runtime response shapes stay in lock-step.

integer

limit

Page size that was applied.

integer

offset

Pagination offset that was applied.

integer

Example

{
  "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"
    },
    "total": 137,
    "limit": 50,
    "offset": 0
  }
}

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

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

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

GSC not connected or Site Audit content data unavailable

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

Validation error or invalid date range

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

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

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."
  }
}