Skip to content

Add Rank Tracker Keywords

POST
/api/v1/keywords
curl --request POST \
--url https://sitechecker.pro/api/v1/keywords \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "project_id": 123, "keywords": [ "buy shoes", "shoe store" ], "geos": [ { "country_code": "US", "language_code": "en", "search_engine": "google", "device": "desktop", "location": "New York,New York,United States" }, { "country_code": "GB", "language_code": "en" } ] }'

Starts tracking keywords in an existing project. Every keyword is tracked in every geo: the request creates keywords × geos tracked keywords (at most 500 pairs per request, 100 keywords and 10 geos). Keywords are trimmed, lower-cased and deduplicated. Pairs the project already tracks are not duplicated: they are returned with created=false, so a retried request is safe and always answers 200. New pairs count towards the plan keyword limit; when the request would exceed it, nothing is added and the answer is 403 QUOTA_EXCEEDED. Positions appear after the next rank check — read them with GET /api/v1/keywords. Valid geo values come from GET /api/v1/rank_tracker_countries, /rank_tracker_languages and /rank_tracker_locations. All invalid keywords and geo fields are reported together in one 422.

Media typeapplication/json
object
project_id
required
integer
keywords
required

Keywords to track, up to 100, each up to 255 characters.

Array<string>
>= 1 items <= 100 items
geos
required

Where to track every keyword, up to 10.

Array<object>
>= 1 items <= 10 items

Where and how a keyword is tracked. Codes are case-insensitive. Valid values come from GET /api/v1/rank_tracker_countries, /rank_tracker_languages and /rank_tracker_locations.

object
country_code
required

ISO 3166-1 alpha-2 country code.

string
language_code
required

ISO 639-1 language code.

string
search_engine
string
default: google
Allowed values: google bing yahoo
device

Mobile is available for google only.

string
default: desktop
Allowed values: desktop mobile
location

Optional Google location: a location_name or location_id from GET /api/v1/rank_tracker_locations. Omit or send an empty string to track the whole country. Google only.

string
Example
{
"project_id": 123,
"keywords": [
"buy shoes",
"shoe store"
],
"geos": [
{
"country_code": "US",
"language_code": "en",
"search_engine": "google",
"device": "desktop",
"location": "New York,New York,United States"
},
{
"country_code": "GB",
"language_code": "en"
}
]
}

Every requested keyword × geo pair, new and already tracked

Media typeapplication/json
object
data
object
project_id
integer
tracked_keywords
Array<object>

A requested keyword × geo pair and whether this request started tracking it.

object
tracked_keyword_id

ID of the tracked keyword: one keyword in one geo. Pass it to GET /api/v1/keywords, GET /api/v1/keyword_daily_positions, GET /api/v1/serp_snapshot and DELETE /api/v1/keywords.

integer
keyword

Keyword as stored: trimmed and lower-cased.

string
search_engine
string
Allowed values: google bing yahoo
device
string
Allowed values: desktop mobile
country_code
string
country_name
string
language_code
string
language_name
string
location_id

Opaque location id; null when the whole country is tracked.

string
nullable
location_name

Canonical Google location name; null when the whole country is tracked.

string
nullable
created

True when this request added the pair; false when the project already tracked it.

boolean
meta
object
created

Pairs this request started tracking.

integer
existing

Pairs the project already tracked.

integer
Example
{
"data": {
"project_id": 123,
"tracked_keywords": [
{
"tracked_keyword_id": 987654,
"keyword": "buy shoes",
"search_engine": "google",
"device": "desktop",
"country_code": "US",
"country_name": "United States",
"language_code": "en",
"language_name": "English",
"location_id": "loc_TmV3IFlvcmssTmV3IFlvcmssVW5pdGVkIFN0YXRlcw",
"location_name": "New York,New York,United States",
"created": true
}
]
},
"meta": {
"created": 3,
"existing": 1
}
}

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid or missing API key."
}
}

No active API entitlement, view-only access to the project (ACCESS_DENIED), or the plan keyword limit would be exceeded (QUOTA_EXCEEDED, see ErrorQuotaExceeded)

Media typeapplication/json
One of:

Returned as MISSING_PUBLIC_API_ACCESS when the account has no active API entitlement, as ACCESS_DENIED when the project is shared with the account at an access level that does not allow this request (a project of another account is reported as 404 PROJECT_NOT_FOUND instead), and as ACCOUNT_BLOCKED or ACCOUNT_INACTIVE when the account behind a valid key is blocked or deactivated — a new key will not help, contact support@sitechecker.pro.

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "MISSING_PUBLIC_API_ACCESS",
"message": "API access is not available: the account has no active API entitlement."
}
}

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. A project that belongs to another account is reported as PROJECT_NOT_FOUND, so its existence is not disclosed.

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "PROJECT_NOT_FOUND",
"message": "Project not found."
}
}

Validation error: every invalid keyword and geo field is listed in details

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. Request-body validation errors also carry error.details, listing every invalid field.

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
error
required
object
details

Every invalid field, not only the first one repeated in error.message. Present on request-body validation errors; field is the path inside the body.

Array<object>
object
field
required

Path of the invalid field inside the request body, e.g. url, keywords[0], geos[1].country_code.

string
message
required
string
Example
{
"error": {
"code": "VALIDATION_ERROR",
"message": "project_id is required."
}
}

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Try again later."
}
}

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 ACCOUNT_BLOCKED ACCOUNT_INACTIVE 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 QUOTA_EXCEEDED
message
required
string
Example
{
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error."
}
}