---
title: "Check Rankings Ep"
method: POST
path: "/sites/{site_id}/tracked-keywords/check"
tags: ["sites"]
---

# Check Rankings Ep

`POST /sites/{site_id}/tracked-keywords/check`

## Request

- Base URL: `https://api.xeorank.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.xeorank.com/sites/{site_id}/tracked-keywords/check`
- Auth: API key in header `X-Agent-Key`

Run DataForSEO ranking check for all tracked keywords.

Small sets (<= RANK_CHECK_INLINE_MAX) run inline and return the checked
rows. Larger sets start in the background and return status="started":
~3.5 s of live SERP per keyword would outlast the MCP client's timeout,
and a timed-out caller retried and paid twice (2026-09-26). While a check
is running, a second call returns status="running" instead of starting
another.

## Path parameters

- `site_id` string, required

## Query parameters

- `email` string, nullable
- `due_only` boolean

## Response `200`

Successful Response

- CheckRankingsResponse
  - `checked` integer, required
  - `status` string
  - `run_id` string, nullable
  - `keyword_count` integer, nullable
  - `estimated_seconds` integer, nullable
  - `next_step` string, nullable
  - `not_ranking` integer
  - `failed` integer
  - `errors` string[]
  - `location` string, nullable
  - `note` string, nullable
  - `keywords` TrackedKeywordOut[]
    - `id` string, uuid, required
    - `keyword` string, required
    - `search_volume` integer, nullable
    - `keyword_difficulty` integer, nullable
    - `current_position` integer, nullable
    - `ranking_url` string, nullable
    - `ranking_location_code` integer, nullable
    - `ranking_location_name` string
    - `ranking_location_type` string
    - `ranking_search_engine` string
    - `ranking_language_code` string
    - `ranking_device` string
    - `cpc` number, nullable
    - `competition` number, nullable
    - `last_checked_at` string, date-time, nullable
    - `created_at` string, date-time, required
    - `intent` string, nullable
    - `funnel_stage` string, nullable
    - `cluster_name` string, nullable
    - `source` string, nullable
    - `notes` string, nullable
    - `classified_at` string, date-time, nullable
    - `position_context` string, nullable
    - `checked_days_ago` integer, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/xeorank/apis/seo-intelligence-engine.md) · [All operations](https://skmtc.dev/xeorank/apis/seo-intelligence-engine/llms.txt) · [OpenAPI document](https://skmtc.dev/xeorank/apis/seo-intelligence-engine/revisions/449a3fd73454?raw)