Analysis & auditGET$0.012
/v1/rank-check
Google organic position of a domain for a keyword, plus the top-10 list — from a licensed SERP feed, never scraped.
Returns the 1-based organic position of the domain inside the checked window, the ranking URL and title, and the first ten results so an agent can see who is above it. position is null when the domain is not in the window — widen num to look deeper.
Parameters#
| Name | Description | |
|---|---|---|
keyword | required | search query (1–120 chars) |
domain | required | hostname to find, e.g. example.com (subdomains match) |
gl | optional | country code, default us |
hl | optional | language code, default en |
num | optional | results window to check, 10–50 (default 20) |
Request#
Plain GET. Without a payment header the response is a 402 carrying the price; an x402 client pays and retries on its own — see the quickstart.
GET https://citable.run/v1/rank-check?keyword=seo+api&domain=dataforseo.com
Response#
200 with the JSON below (trimmed) and the settlement signature in the PAYMENT-RESPONSE header. Every paid response also carries price and cluster.
{
"keyword": "seo api",
"domain": "dataforseo.com",
"position": 1,
"url": "https://dataforseo.com/",
"title": "DataForSEO: Powerful API Stack For Data-Driven SEO Tools",
"checked": 19,
"gl": "us",
"hl": "en",
"top10": [
{ "position": 1, "domain": "dataforseo.com", "url": "https://dataforseo.com/", "title": "DataForSEO: Powerful API Stack For Data-Driven SEO Tools" },
{ "position": 2, "domain": "authoritas.com", "url": "https://www.authoritas.com/apis", "title": "3 APIs for SEO pros - get a free API key | Authoritas" },
{ "position": 3, "domain": "reddit.com", "url": "https://www.reddit.com/r/SEO_LLM/comments/…", "title": "SEOs, what's the best API for SEO you've actually ..." }
],
"price": "$0.012",
"cluster": "mainnet"
}Errors#
Any non-200 cancels the payment — errors are free.
| Status | Code | When |
|---|---|---|
| 400 | invalid_keyword | keyword missing or longer than 120 chars |
| 400 | invalid_domain | domain is not a hostname |
| 502 | upstream_failed | the data source did not answer — nothing is charged |
| 503 | not_configured | this deployment has no credentials for the source — nothing is charged |
MCP tool#
The same call from Claude, Codex or Cursor once citable-mcp is installed. Arguments mirror the parameters above.
citable_rank_check(keyword, domain, gl?, hl?, num?) $0.012Source & latency#
| Data source | Typical latency |
|---|---|
| DataForSEO SERP (licensed live feed) | ~6–13 s at the default window; deeper windows take longer |