Rank Tracking

The rank-tracking endpoints return stored keyword ranking snapshots collected from the webmaster providers you have connected (Google Search Console, Bing Webmaster Tools, Yandex Webmaster). Snapshots are synced on a schedule, so this is never a live SERP check. All reads cost 0 credits, and alert settings can also be updated with an API key.

Before you call

Endpoints at a glance

Every route needs your API key in X-API-Key and shares the 60 requests per minute per key rate limit. See Authentication. Responses are plain objects, not wrapped in the usual data / credits_used envelope.

Engines and availability

Bing and Yandex tracking is opt-in per account, so many accounts only have Google connected. Read engine fields carefully:

• A missing engine key in a site's providers or a keyword's engines means that engine is not connected or attached. It is never a zero or bottom rank. To tell "not enabled for your account" apart from "enabled but not attached to this site", compare against enabled_engines on the rankings response.
• A present engine with availability other than available can carry null position, clicks and impressions. That is a data-quality or sync-timing signal, not evidence that the keyword ranks nowhere.
• Positions are provider-reported averages over the returned period, not live, neutral-location SERP ranks.

availability is one of:

Treat every value other than available as a data-quality or timing signal and check data_as_of, last_success_at and error_code before drawing conclusions.

GET /v1/rank-tracking/sites

Lists the websites configured for rank tracking, including each engine's attached primary property and sync freshness.

Example

curl "https://api.rankparse.com/v1/rank-tracking/sites" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/rank-tracking/sites",
    headers={"X-API-Key": "rp_your_key"},
)
for site in res.json()["sites"]:
    print(site["site_id"], site["canonical_host"], list(site["providers"]))

const res = await fetch("https://api.rankparse.com/v1/rank-tracking/sites", {
  headers: { "X-API-Key": "rp_your_key" },
});
const { sites } = await res.json();

Response

{
  "sites": [
    {
      "site_id": "site_abc123",
      "canonical_host": "example.com",
      "display_name": "example.com",
      "providers": {
        "google": {
          "engine": "google",
          "property_id": "prop_g1",
          "property_url": "https://example.com/",
          "is_active": true,
          "last_synced_at": 1756112400000,
          "data_as_of": "2026-08-25",
          "latest_sync_status": "succeeded",
          "latest_sync_error_code": null,
          "search_appearance": {
            "as_of_date": "2026-08-25",
            "entries": [
              { "appearance": "AMP_BLUE_LINK", "clicks": 3, "impressions": 120, "ctr": 0.025, "position": 8.4 }
            ]
          },
          "connection": { "label": "you@example.com", "status": "active" }
        }
      }
    }
  ]
}

Response fields

A missing key (no bing above) means Bing is not connected for this site, not that it has zero rankings.

GET /v1/rank-tracking/keywords

Lists the tracked keyword IDs and query text for one site.

Parameters

Example

curl "https://api.rankparse.com/v1/rank-tracking/keywords?site_id=site_abc123&limit=50" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/rank-tracking/keywords",
    headers={"X-API-Key": "rp_your_key"},
    params={"site_id": "site_abc123", "limit": 50},
)
print(res.json()["keywords"])

const params = new URLSearchParams({ site_id: "site_abc123", limit: "50" });
const res = await fetch(`https://api.rankparse.com/v1/rank-tracking/keywords?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
const { keywords } = await res.json();

Response

{
  "site_id": "site_abc123",
  "canonical_host": "example.com",
  "keywords": [
    { "id": "kw_1", "query": "buy widgets", "created_at": 1753900800000 }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

created_at is Unix time in milliseconds. total is the number of tracked keywords on the site, so page with offset until you have them all.

GET /v1/rank-tracking/rankings

Returns current-versus-previous-period ranking summaries for a site's tracked keywords, across every engine enabled for your account by default.

Parameters

Example

curl "https://api.rankparse.com/v1/rank-tracking/rankings?site_id=site_abc123&engine=all&period_days=28" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/rank-tracking/rankings",
    headers={"X-API-Key": "rp_your_key"},
    params={"site_id": "site_abc123", "engine": "all", "period_days": 28},
)
body = res.json()
for kw in body["keywords"]:
    google = kw["engines"].get("google")
    if google and google["availability"] == "available":
        print(kw["query"], google["current"]["position"], google["movement"])

const params = new URLSearchParams({
  site_id: "site_abc123",
  engine: "all",
  period_days: "28",
});
const res = await fetch(`https://api.rankparse.com/v1/rank-tracking/rankings?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
const { keywords, enabled_engines } = await res.json();

To look at one keyword, add &keyword_id=kw_1. To read a single engine, set engine=google, bing or yandex.

Response

{
  "site_id": "site_abc123",
  "canonical_host": "example.com",
  "enabled_engines": ["google", "bing", "yandex"],
  "period_days": 28,
  "limit": 100,
  "offset": 0,
  "total": 1,
  "keywords": [
    {
      "id": "kw_1",
      "query": "buy widgets",
      "engines": {
        "google": {
          "engine": "google",
          "property_id": "prop_g1",
          "property_url": "https://example.com/",
          "availability": "available",
          "data_as_of": "2026-08-25",
          "top_page": "https://example.com/widgets",
          "current_period": { "start_date": "2026-07-29", "end_date": "2026-08-25" },
          "previous_period": { "start_date": "2026-07-01", "end_date": "2026-07-28" },
          "current": { "clicks": 12, "impressions": 340, "ctr": 0.035, "position": 6.2, "click_position": 5.9 },
          "previous": { "clicks": 9, "impressions": 310, "ctr": 0.029, "position": 7.1, "click_position": 6.8 },
          "movement": 0.9,
          "countries": [
            { "country": "usa", "clicks": 8, "impressions": 210, "ctr": 0.038, "position": 5.8 },
            { "country": "gbr", "clicks": 2, "impressions": 60, "ctr": 0.033, "position": 7.0 }
          ]
        },
        "bing": {
          "engine": "bing",
          "property_id": "prop_b1",
          "property_url": "https://example.com/",
          "availability": "provider_limited",
          "data_as_of": "2026-08-20",
          "top_page": null,
          "current_period": { "start_date": "2026-07-29", "end_date": "2026-08-25" },
          "previous_period": { "start_date": "2026-07-01", "end_date": "2026-07-28" },
          "current": { "clicks": null, "impressions": null, "ctr": null, "position": null, "click_position": null },
          "previous": { "clicks": null, "impressions": null, "ctr": null, "position": null, "click_position": null },
          "movement": null,
          "countries": null
        }
      }
    }
  ]
}

Response fields

In the example, bing is provider_limited with entirely null metrics. That is a data-quality gap for the period, not a signal that the keyword does not rank on Bing. yandex is absent from this keyword's engines even though it appears in enabled_engines: Yandex is enabled for the account but not attached to this website.

GET /v1/rank-tracking/history

Returns day-by-day history for one keyword on one engine over a date range. History is always single-engine: engine is required and all is not accepted. Call rankings first to compare engines.

Parameters

Example

curl "https://api.rankparse.com/v1/rank-tracking/history?site_id=site_abc123&keyword_id=kw_1&engine=google&start_date=2026-08-01&end_date=2026-08-25" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/rank-tracking/history",
    headers={"X-API-Key": "rp_your_key"},
    params={
        "site_id": "site_abc123",
        "keyword_id": "kw_1",
        "engine": "google",
        "start_date": "2026-08-01",
        "end_date": "2026-08-25",
        "dimension": "device",
    },
)
for row in res.json()["rows"]:
    print(row["date"], row["device"], row["position"])

const params = new URLSearchParams({
  site_id: "site_abc123",
  keyword_id: "kw_1",
  engine: "google",
  start_date: "2026-08-01",
  end_date: "2026-08-25",
});
const res = await fetch(`https://api.rankparse.com/v1/rank-tracking/history?${params}`, {
  headers: { "X-API-Key": "rp_your_key" },
});
const { rows } = await res.json();

Response

{
  "site_id": "site_abc123",
  "keyword_id": "kw_1",
  "query": "buy widgets",
  "engine": "google",
  "property_id": "prop_g1",
  "property_url": "https://example.com/",
  "availability": "available",
  "data_as_of": "2026-08-25",
  "last_attempt_at": 1756112400000,
  "last_success_at": 1756112400000,
  "error_code": null,
  "start_date": "2026-08-01",
  "end_date": "2026-08-25",
  "dimension": "total",
  "rows": [
    { "date": "2026-08-01", "clicks": 1, "impressions": 30, "ctr": 0.033, "position": 6.8, "click_position": 6.5 },
    { "date": "2026-08-03", "clicks": 0, "impressions": 25, "ctr": 0, "position": 7.2, "click_position": null }
  ]
}

Response fields

• A missing calendar date (2026-08-02 above) means there was no synced observation that day. Never treat a gap as a zero or a dropped rank.
• Device rows exist only where the provider synced them: always for Google, and for Yandex only when its per-device breakdown is switched on. An empty device history next to a populated total history means "not synced per device", not "no traffic". Bing has no device breakdown.

GET /v1/rank-tracking/alerts

Lists recorded rank-change alert events for one site, newest first. Events are recorded daily while alerts are enabled for the site (see Alert settings). This is the full history, including changes that were left out of the weekly email because their net movement cancelled out.

Parameters

curl "https://api.rankparse.com/v1/rank-tracking/alerts?site_id=site_abc123" \
  -H "X-API-Key: rp_your_key"

import requests

res = requests.get(
    "https://api.rankparse.com/v1/rank-tracking/alerts",
    headers={"X-API-Key": "rp_your_key"},
    params={"site_id": "site_abc123"},
)
for alert in res.json()["alerts"]:
    print(alert["metric_date"], alert["query"], alert["alert_type"])

const res = await fetch(
  "https://api.rankparse.com/v1/rank-tracking/alerts?site_id=site_abc123",
  { headers: { "X-API-Key": "rp_your_key" } },
);
const { alerts } = await res.json();

Response

{
  "site_id": "site_abc123",
  "total": 1,
  "limit": 100,
  "offset": 0,
  "alerts": [
    {
      "keyword_id": "kw_1",
      "query": "buy widgets",
      "engine": "google",
      "property_id": "prop_g1",
      "metric_date": "2026-08-25",
      "alert_type": "entered_top_10",
      "old_position": 12.4,
      "new_position": 8.9,
      "detected_at": 1756166400000,
      "digest_date": "2026-08-26",
      "delivered_at": null
    }
  ]
}

Response fields

Alert types

Detection compares each keyword's position on the property's freshest synced day with its average position over the prior 7 days, per engine.

Only the most specific boundary crossing is recorded per direction (entering the top 3 implies entering the top 10, so only entered_top_3 is recorded). moved_up and moved_down are recorded independently of boundary events. Only keyword and engine pairs whose availability is available generate events, and a null position is never treated as a move.

Alert settings

Alerts are opt-in and off by default, set per website. Read the settings with GET, change them with PATCH. Both take site_id as a query parameter.

GET response

{
  "site_id": "site_abc123",
  "enabled": false,
  "email_override": null,
  "move_threshold": 5,
  "last_detected_date": null
}

PATCH merges only the fields you send; anything you omit keeps its current value. Send site_id in the query string, the fields in a JSON body.

curl -X PATCH "https://api.rankparse.com/v1/rank-tracking/alert-settings?site_id=site_abc123" \
  -H "X-API-Key: rp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "move_threshold": 5}'

import requests

res = requests.patch(
    "https://api.rankparse.com/v1/rank-tracking/alert-settings",
    headers={"X-API-Key": "rp_your_key"},
    params={"site_id": "site_abc123"},
    json={"enabled": True, "move_threshold": 5},
)
print(res.json())

const res = await fetch(
  "https://api.rankparse.com/v1/rank-tracking/alert-settings?site_id=site_abc123",
  {
    method: "PATCH",
    headers: {
      "X-API-Key": "rp_your_key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ enabled: true, move_threshold: 5 }),
  },
);
console.log(await res.json());

The response is the full settings object, in the same shape as GET.

Weekly rank-change emails

Detection runs daily for each site with alerts enabled. Emails go out on Sundays at 18:00 UTC, and only when meaningful changes remain after consolidation.

• Opt-in per website. Nothing is sent until you set enabled to true.
• One email per recipient. If you track several websites, each recipient gets at most one digest per week covering all of their sites. A per-site email_override can split sites across different recipients.
• One net change per keyword. Repeated moves for the same website, keyword and engine in the week are shown as a single net change. Moves that cancel out, or that fall below the site's move_threshold, are left out.
• No meaningful changes means no email.
• Failed sends are retried. If the email service does not accept a send, those events stay pending and are included in the next weekly run.
• Positions in the email are provider-reported averages, not live SERP checks. Digests never contain tokens or API keys.
• Events older than 400 days are pruned.

The dashboard shows each website's alert state read-only under its Settings, in the Rank alerts section. Change it with the API or the MCP tool below.

Behavior and limits

• All routes cost 0 credits and are limited only by the 60 requests per minute rate limit.
• site_id and keyword_id are scoped to your workspace. An ID that belongs to someone else returns the same 404 as one that does not exist.
• limit and offset on keywords, rankings and alerts: invalid or out-of-range values fall back to the defaults instead of returning an error. period_days is validated strictly.

Errors

All errors use the standard shape { "error", "code", "message" }. See Error codes.

MCP tools

All seven tools are on the API-key MCP endpoint (mcp.rankparse.com) only. The secure OAuth connector does not include them. Reads cost 0 credits. See MCP Server.

Distinct from GSC and Google Ads

Rank tracking, Google Search Console and Google Ads are three separate data products. None of them changes the others:

• Google Search Console endpoints expose live, Google-only Search Console dimensions: pages, devices, countries, sitemaps and URL inspection.
• Google Ads keyword research returns search volume and competition, never organic rankings, for any engine.
• Rank tracking is the only family that reads stored Google, Bing and Yandex position snapshots side by side.

Related