Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

Rank Tracker SERP Opportunity Pages

GET
/api/v1/serp_opportunities
curl --request GET \
  --url 'https://sitechecker.pro/api/v1/serp_opportunities?project_id=12345&content_type=listings&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Returns the monthly list of URLs identified as SERP opportunities for the project. This report is a monthly snapshot and takes no date range; the snapshot dates come back in the response meta.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
project_id
required
integer
Example
12345

Project ID.

search
string

Substring search in title or URL.

content_type
string
Allowed values: listings info ugc news_media competitors reviews stores government education ai_chats web_dev

Filter by content type (lowercase machine value).

keyword
string

Return URLs ranking for keywords containing this text. Aggregates are recomputed over the matching keywords only.

page_url
string

Substring filter on the opportunity URL.

order_by
string

Sort as “_asc” or “_desc”. Sortable fields: page_url, title, average_position, keywords_count.

limit
integer
default: 50 >= 1 <= 50

Page size. Rank Tracker list endpoints cap at 50 rows per request.

offset
integer
0

Pagination offset.

Responses

Section titled “Responses”

200

Section titled “200”

Paginated SERP opportunity URLs

Media typeapplication/json
object
data
Array<object>

Monthly SERP opportunity URL aggregate. Use opportunity_id for the serp_opportunity_keywords drilldown; ids may expire after the monthly snapshot regeneration.

object
opportunity_id

Opaque opportunity id. Pass it to the opportunity keywords endpoint.

string
page_url

URL identified as an opportunity.

string
domain

Host of that URL.

string
nullable
title

Page title as seen in the SERP.

string
nullable
content_type

Primary content type the page was classified as.

string
nullable
content_types

All content types the page was classified as.

Array<string>
average_position

Mean position this URL holds across the keywords it ranks for.

number format: float
nullable
keywords_count

Tracked keywords this URL ranks for.

integer
snapshot_date

Date of the monthly snapshot this row comes from.

string format: date
nullable
next_snapshot_date

Date the next snapshot is due.

string format: date
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": [
    {
      "opportunity_id": "opp_aHR0cHM6Ly93d3cuc2VvcHRpbWVyLmNvbS8",
      "page_url": "https://www.seoptimer.com/",
      "domain": "seoptimer.com",
      "title": "SEOptimer: Analyze Websites",
      "content_type": "competitors",
      "content_types": [
        "competitors",
        "info"
      ],
      "average_position": 22.6,
      "keywords_count": 131,
      "snapshot_date": "2026-04-25",
      "next_snapshot_date": "2026-05-25"
    }
  ],
  "meta": {
    "total": 131,
    "limit": 50,
    "offset": 0,
    "snapshot_date": "2026-04-25",
    "next_snapshot_date": "2026-05-25"
  }
}

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

422

Section titled “422”

Validation error (including date_from/date_to, which this snapshot endpoint rejects)

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