Keyword Rankings API endpoint

POST /v1/keywords/rankingsAbout Keyword Rankings

Where a site ranks in Google organic results for one to five keywords: position, ranking page, competitors, the top 10 and the AI Overview. Billed per keyword checked.

Overview

Send one to five keywords and your domain. For each keyword Cite42 reads Google’s top 100 organic results in one country (40 supported) on desktop or mobile, and returns your best position (organic results only), the same result’s absolutePosition counting every block on the page, the ranking url, every URL of yours in the top 100, up to five competitors, the top 10 and whether the aiOverview cites you. A url in the request checks whether that page is the one Google shows.

Billing is $0.09 per keyword checked. A keyword whose results could not be fetched comes back as failed and is free; if every keyword fails, the call returns an error and nothing is billed. citesDomain is null when no domain was given or the overview’s sources could not be read.

Google shows different result sets to different searchers for broad keywords, so a result is one live sample; the response says so in note. To follow positions over time, save the keywords in a tracker with the keyword_rankings measurement: up to 100 keywords, weekly or monthly, with big moves checked twice before they are reported.

Reference

POST/v1/keywords/rankings

$0.45 · flat per call

Parameters

keywordsstring[]required
One to 5 distinct search terms to check, as people type them into Google. Each is billed separately.
domainstringoptional
Your site, e.g. example.com. Covers www and subdomains. Omit both domain and url to get only the top results; a full url on its own stands for its domain.
urlstringoptional
Optional page that should rank, as a full URL or a path such as /pricing. The result says whether it is the page Google shows.
competitorsstring[]optional
Up to 5 competitor domains to report positions for.
countrystringoptional
ISO-2 country code of the Google market to check. Defaults to "us". Default: "us".
languagestringoptional
Optional ISO-2 language code. Defaults to the country's main language.
deviceenumoptional
Desktop or mobile results. Defaults to desktop. Default: "desktop".
Values:desktopmobile

Request

curl https://www.cite42.dev/api/v1/keywords/rankings \
  -X POST \
  -H "Authorization: Bearer $CITE42_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["ai visibility api"],"domain":"cite42.dev","competitors":["llmrefs.com"]}'

Response

{
  "domain": "cite42.dev",
  "country": "us",
  "language": "en",
  "device": "desktop",
  "depth": 100,
  "results": [
    {
      "keyword": "ai visibility api",
      "status": "ranked",
      "position": 84,
      "absolutePosition": 93,
      "url": "https://www.cite42.dev/blog/ai-visibility-apis",
      "matchingUrls": [
        {
          "url": "https://www.cite42.dev/blog/ai-visibility-apis",
          "position": 84
        },
        {
          "url": "https://www.cite42.dev/blog/ai-visibility-tools",
          "position": 97
        }
      ],
      "competitors": [
        {
          "domain": "llmrefs.com",
          "position": 3,
          "url": "https://llmrefs.com/ai-search-visibility"
        }
      ],
      "topResults": [
        {
          "position": 1,
          "domain": "growthmethod.com",
          "url": "https://growthmethod.com/ai-visibility-tools/",
          "title": "AI Visibility Tools Compared: How They Actually Work"
        },
        {
          "position": 2,
          "domain": "www.integrate.io",
          "url": "https://www.integrate.io/blog/best-ai-visibility-tracking-tools/",
          "title": "Best AI Visibility Tracking Tools (2026)"
        },
        {
          "position": 3,
          "domain": "llmrefs.com",
          "url": "https://llmrefs.com/ai-search-visibility",
          "title": "AI Search Visibility (AI SEO / AEO / GEO Tracker)"
        }
      ],
      "aiOverview": {
        "present": true,
        "citesDomain": null,
        "citedUrls": []
      },
      "serpFeatures": [
        "ai_overview",
        "related_searches"
      ],
      "checkedAt": "2026-10-20T11:45:25.000Z"
    }
  ],
  "note": "Google can show different results to different searchers, especially for broad keywords, so each check is one live sample from the chosen country and device.",
  "requestId": "…",
  "billing": {
    "cost": {
      "microCredits": 9000,
      "usd": "0.09"
    },
    "balance": {
      "microCredits": 1336000,
      "usd": "13.36"
    }
  }
}