Skip to content
Sitechecker API documentationSitechecker API documentationSitechecker API

Rank Tracker Keyword List

GET
/api/v1/keywords
curl --request GET \
  --url 'https://sitechecker.pro/api/v1/keywords?project_id=12345&date_from=2026-02-22&date_to=2026-05-22&search_engine=google&device=desktop&location_id=loc_TmV3IFlvcmssVW5pdGVkIFN0YXRlcw&language_code=en&group_id=SG9tZSBQYWdlcw&rankings=all&movement_window=1d&serp_feature=ads&ai_overview=all&fields=cpc&limit=50&offset=0' \
  --header 'Authorization: Bearer <token>'

Returns tracked keywords with ranking, visibility, search volume, landing page, and comparison metrics for the selected date range. Ranking filters are cumulative — top_10 covers positions 1-10 — while the distribution buckets in the response are exclusive.

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

Start of the Rank Tracker date range (inclusive, Y-m-d). Clamped to the project’s available indicator dates.

date_to
required
string format: date
Example
2026-05-22

End of the Rank Tracker date range (inclusive, Y-m-d). Visibility-style fields are snapshots for the latest available check within this range (as_of_date).

keyword
string

Substring keyword text search.

tracked_keyword_id
integer

Direct lookup of one tracked keyword row.

search_engine
string
Example
google

Search engine machine value from rank_tracker_filter_values (e.g. google).

device
string
Allowed values: desktop mobile tablet

Device filter.

location_id
string
Example
loc_TmV3IFlvcmssVW5pdGVkIFN0YXRlcw

Opaque location id from rank_tracker_filter_values tracking_profiles (loc_… value).

language_code
string
Example
en

Language code (ISO alpha-2) from rank_tracker_filter_values.

group_id
string
Example
SG9tZSBQYWdlcw

Keyword group id from the groups endpoint (opaque value).

rankings
string
default: all
Allowed values: all top_1 top_3 top_10 top_30 top_50 top_100 no_position moved_up moved_down not_changed

Ranking filter. Bucket filters are cumulative (top_10 = positions 1-10); response distribution buckets are exclusive. Movement filters (moved_up/moved_down/not_changed) compare against the movement_window snapshot.

movement_window
string
default: 7d
Allowed values: 1d 7d 30d 90d all_time

Comparison window for movement rankings filters. Only valid with rankings=moved_up, moved_down or not_changed. Default: 7d.

serp_feature
string
Allowed values: ads featured_snippet people_also_ask shopping top_carousel video

Filter keywords whose SERP contains the feature.

ai_overview
string
default: all
Allowed values: all with_overview without_overview

AI Overview presence filter. Default: all.

target_url
string

Substring filter on the target URL set for the keyword.

ranked_url
string

Substring filter on the URL that actually ranks.

volume_from
integer

Minimum search volume.

volume_to
integer

Maximum search volume.

fields
string
Allowed values: cpc ad_competition created_at updated_at allintitle kgr serp_features gsc.impressions gsc.clicks gsc.average_position gsc.ctr ai_overview_user_position ai_overview_citations_count ai_overview_citation_url gsc_metrics ai_overview

Comma-separated optional response fields, each requested under its own name (e.g. fields=cpc,gsc.clicks). gsc_metrics and ai_overview are shorthands for their whole block (gsc.* and ai_overview_). gsc. metrics reflect the latest synced GSC snapshot, not the selected date range.

order_by
string

Sort as “_asc” or “_desc”, e.g. position_asc. Sortable fields: position, volume, keyword, change_1d/7d/30d/90d/all_time, best_position, created_at, updated_at.

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 tracked keywords

Media typeapplication/json
object
data
Array<object>

Tracked keyword row. position uses the Rank Tracker table logic for the selected range; null = not ranked. Deltas keep the backend sign convention: negative = improved. Optional fields appear only when requested via fields=; gsc.* reflect the latest synced GSC snapshot, not the date range.

object
tracked_keyword_id

Tracked keyword id. Pass it to the daily positions and SERP snapshot endpoints.

integer
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
country_name

Display name of that country.

string
nullable
language_code

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

string
nullable
language_name

Display name of that language.

string
nullable
position

Current ranking position. Null when the keyword does not rank in the top 100.

integer
nullable
volume

Monthly search volume.

integer
nullable
ranked_url

URL that currently ranks for the keyword.

string
nullable
target_url

URL the keyword is meant to rank with, when one is configured.

string
nullable
group_id

Id of the keyword group this keyword belongs to.

string
nullable
group_name

Display name of that group.

string
nullable
best_position

Best position ever recorded for this keyword.

integer
nullable
best_position_date

Date that best position was recorded.

string format: date
nullable
change_1d

Position change over the last day. Negative means the ranking improved.

integer
nullable
change_7d

Position change over the last 7 days. Negative means the ranking improved.

integer
nullable
change_30d

Position change over the last 30 days. Negative means the ranking improved.

integer
nullable
change_90d

Position change over the last 90 days. Negative means the ranking improved.

integer
nullable
change_all_time

Position change since tracking began. Negative means the ranking improved.

integer
nullable
has_ai_overview

Whether the SERP for this keyword returns an AI Overview.

boolean
brand_mentioned

Whether that AI Overview mentions the brand.

boolean
cpc

Only with fields=cpc.

number format: float
nullable
ad_competition

Only with fields=ad_competition.

integer
nullable
created_at

Only with fields=created_at.

string format: date
nullable
updated_at

Only with fields=updated_at.

string format: date
nullable
allintitle

Only with fields=allintitle.

integer
nullable
kgr

Only with fields=kgr.

number format: float
nullable
serp_features

Only with fields=serp_features. Public machine values.

Array<string>
nullable
gsc

Latest synced GSC snapshot values. Each metric is requested on its own (fields=gsc.impressions, gsc.clicks, gsc.average_position, gsc.ctr) or all at once with fields=gsc_metrics; the block carries only the requested metrics.

object
impressions

Only with fields=gsc.impressions.

integer
nullable
clicks

Only with fields=gsc.clicks.

integer
nullable
average_position

Only with fields=gsc.average_position. GSC average position — not the Rank Tracker position.

number format: float
nullable
ctr

Only with fields=gsc.ctr. Percentage value.

number format: float
nullable
ai_overview_user_position

Only with fields=ai_overview_user_position (or fields=ai_overview). Domain position inside the AI Overview.

integer
nullable
ai_overview_citations_count

Only with fields=ai_overview_citations_count (or fields=ai_overview). Number of links cited in the AI Overview.

integer
nullable
ai_overview_citation_url

Only with fields=ai_overview_citation_url (or fields=ai_overview). Cited URL of the domain, if any.

string
nullable
meta
object
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
{
  "data": [
    {
      "tracked_keyword_id": 123456,
      "keyword": "seo checker",
      "search_engine": "google",
      "device": "desktop",
      "location_id": "loc_TmV3IFlvcmssVW5pdGVkIFN0YXRlcw",
      "location_name": "New York,United States",
      "country_code": "US",
      "country_name": "United States",
      "language_code": "en",
      "language_name": "English",
      "position": 3,
      "volume": 2900,
      "ranked_url": "/de/on-page-seo-checker/",
      "target_url": "/de/on-page-seo-checker/",
      "group_id": "SG9tZSBQYWdlcw",
      "group_name": "Home Pages",
      "best_position": 2,
      "best_position_date": "2025-10-26",
      "change_1d": -1,
      "change_7d": 2,
      "change_30d": 7,
      "change_90d": 83,
      "change_all_time": 99,
      "has_ai_overview": true,
      "brand_mentioned": false,
      "cpc": 11.24,
      "ad_competition": 10,
      "created_at": "2025-04-08",
      "updated_at": "2026-05-21",
      "allintitle": 53,
      "kgr": 0.02,
      "serp_features": [
        "featured_snippet",
        "video"
      ],
      "gsc": {
        "impressions": 3278,
        "clicks": 27,
        "average_position": 12.4,
        "ctr": 0.82
      },
      "ai_overview_user_position": 3,
      "ai_overview_citations_count": 2,
      "ai_overview_citation_url": "/de/on-page-seo-checker/"
    }
  ],
  "meta": {
    "total": 137,
    "limit": 50,
    "offset": 0
  }
}

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

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