Skip to main content
Use checks when you need a fresh position for one keyword immediately. Each keyword already belongs to one location-language market and one device. The check inherits that exact target from the keyword resource. To check the same phrase in another language, create a separate keyword target with a qualified location_key, such as ES/Andalusia/Malaga@en, then run the check for that keyword ID. An unqualified key uses the country’s default language. See Markets and languages.

​
Run rank check

Body is optional:
Use a specific connected provider:
If provider_id is omitted, the primary connected SERP provider for the project is used. Response status is 201 when the check completes during the request.
attempts is null when the selected provider succeeds immediately. When fallback providers are tried first, it is an array of { "provider", "message" } objects for the failed attempts.

​
Position semantics

position is the 1-based position of the best matching organic result within the requested depth. Ads, featured snippets, local packs, and other SERP features do not change that value. ranking_url preserves the URL reported by the provider; bisibility does not replace it after resolving redirects or canonicals. position: null is a valid ranking observation only when a completed check found no matching organic result within the requested depth. A malformed provider payload fails the provider attempt and can use the configured fallback chain; it is not stored as a completed no-match.

​
Queued response and correlation

When inline execution is unavailable, the request queues a rank-check run. The response status is 202; id is the public run ID and status is queued:
Poll the keyword’s completed rank-check history and select the row whose run_id equals the queued response’s id. That row contains the final position and its rank-check id:
run_id is null only for legacy rank-check rows that predate runs.

​
Failure modes

Budget failures are returned as budget_exhausted problem responses. Provider failures are returned as provider_unavailable problem responses.