SERP Opportunity Keywords

GET

/api/v1/serp_opportunity_keywords

curl --request GET \
  --url 'https://sitechecker.pro/api/v1/serp_opportunity_keywords?project_id=12345&opportunity_id=opp_aHR0cHM6Ly93d3cuc2VvcHRpbWVyLmNvbS8&limit=100&offset=0' \
  --header 'Authorization: Bearer <token>'

• Production

Returns the keywords for which one selected SERP opportunity URL ranks.

Authorizations

• bearerAuth

Parameters

Query Parameters

project_id

required

integer

Example

12345

Project ID.

opportunity_id

required

string

Example

opp_aHR0cHM6Ly93d3cuc2VvcHRpbWVyLmNvbS8

Stable SERP opportunity id returned by serp_opportunities (opp_… value). May expire after the monthly snapshot regeneration (404).

order_by

string

Sort as “_asc” or “_desc”. Sortable fields: keyword, position, volume, kgr.

limit

integer

default: 100 >= 1 <= 100

Page size (max 100).

offset

integer

0

Pagination offset.

Responses

200

Paginated keywords for the opportunity URL

Media typeapplication/json

object

data

Array<object>

Keyword for which the selected opportunity URL ranks in the monthly snapshot. tracked_keyword_id is null in V1.

object

tracked_keyword_id

Tracked keyword id, when the keyword is tracked for this project.

integer

nullable

keyword

Keyword text.

string

search_engine

Search engine the keyword is tracked on.

string

nullable

device

Device the keyword is tracked on.

string

nullable

location_id

Id of the tracked location.

string

nullable

location_name

Display name of the tracked location.

string

nullable

country_code

Country the keyword is tracked for, as ISO-3166-1 alpha-2.

string

nullable

language_code

Language the keyword is tracked for, as ISO-639-1.

string

nullable

position

Position the opportunity URL holds for this keyword.

integer

nullable

volume

Monthly search volume.

integer

nullable

kgr

Keyword Golden Ratio for the keyword — lower means less competition for the volume.

number format: float

nullable

meta

Pagination meta plus monthly snapshot dates.

object

total

Rows matching the request, before pagination.

integer

limit

Page size that was applied.

integer

offset

Pagination offset that was applied.

integer

snapshot_date

Date of the monthly snapshot these rows come from.

string format: date

nullable

next_snapshot_date

Date the next snapshot is due.

string format: date

nullable

Example

{
  "data": [
    {
      "tracked_keyword_id": null,
      "keyword": "seo audit",
      "search_engine": "google",
      "device": "desktop",
      "location_id": "loc_TmV3IFlvcmssVW5pdGVkIFN0YXRlcw",
      "location_name": "New York,United States",
      "country_code": "US",
      "language_code": "en",
      "position": 1,
      "volume": 6600,
      "kgr": 8.5
    }
  ],
  "meta": {
    "total": 131,
    "limit": 50,
    "offset": 0,
    "snapshot_date": "2026-04-25",
    "next_snapshot_date": "2026-05-25"
  }
}

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

422

Validation error

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