Scheduled rank tracker

The scheduled rank tracker runs a rank check for one domain's saved phrases on the schedule you pick, and writes the rows to rank history next to the manual ones. A manual rank check answers "what are they now?"; the tracker answers "what were they on Tuesday?".

The tracker is off by default. Turn it on per domain from PUT /api/local-seo/rank-tracker (cadence: "daily" or "weekly"), then leave it alone. The hourly tick picks it up.

Where

• Web: no UI yet for the tracker settings. Set the cadence over the API or MCP.
• iOS: no UI yet. Same API.
• API/MCP: GET /api/local-seo/rank-tracker?domain_id=… returns the settings, what a run will cost, the last run's status and the next scheduled time. PUT /api/local-seo/rank-tracker with { cadence: "off" | "daily" | "weekly", surfaces?: "local_pack" | "organic" | "local_pack,organic" } turns it on or off. Tools get_rank_tracker, set_rank_tracker.

The GET response is what you read before you turn it on:

{
  "tracker": {
    "cadence": "off",
    "surfaces": ["local_pack", "organic"],
    "keyword_limit": 5,
    "keywords_saved": 12,
    "keywords_tracked": 5,
    "credits_per_run": 20,
    "estimated_monthly_credits": 0,
    "balance": 184,
    "next_run_at": null,
    "last_run_at": "2026-10-02 13:00:11",
    "last_status": "ok",
    "last_reason": null,
    "last_credits": 20
  }
}

Saving the same cadence twice does not bring a run forward; the slot you already have is kept.

What it measures

The same two surfaces a manual check measures:

The default is both surfaces. One phrase on both is 4 credits per run.

A run only measures phrases you have saved as keyword targets on that domain, up to the plan's limit (see below). The tracker takes the oldest phrases first when more are saved than the limit covers. The phrases it covered are still in rank history next to the manual ones, with source = 'scheduled', and the SEO alerts after each run use them.

Cadence and cost

Daily is the heavier tab. Pro's 5 phrases on both surfaces daily is 20 credits a run, about 600 a month, which the 250-credit allowance does not cover. Weekly is 20 credits a run, about 87 a month. The tracker picks up the right cadence; you only see the number.

A run that would overdraw the balance is skipped uncharged. Nothing is paid for a run that did not happen. The reason is on the settings row (last_status: "skipped", last_reason: "insufficient_credits") and a feed row says so once a week, so a tracker that went quiet because the balance ran out is not mistaken for steady ranks.

Plan caps

The tracker is part of Local SEO. Free and Starter have no Local SEO, so no tracker. Pro and Enterprise do; the admin SEO grant on a lower plan unlocks it with Pro's number.

A domain can save more phrases than the cap. The tracker measures the oldest ones first, so what it covers does not depend on what you saved last.

Throughput

One run costs keywords_tracked × surfaces searches. The hourly tick admits at most RANK_TRACKER_UNITS_PER_TICK (60) searches a tick, oldest due first. 60 a tick is at most 1,440 provider searches a day, a small share of what the provider allows, and enough for two Enterprise domains at the cap (25 × 2) or a dozen Pro domains each hour. A large domain that does not fit this tick waits for the next one; a domain smaller than the budget does not push a larger one behind it.

When a run does not happen

A run is skipped, uncharged, with its reason on the settings row and one feed row a week, when:

• The plan does not include Local SEO.
• The balance cannot cover the quoted cost (insufficient_credits).
• The saved business profile is missing, or the saved city is not verified (no_business_profile, the city's code).
• No keyword targets are saved (no_keywords).
• A retried tick already started this hour's run (operation_in_progress).

A provider error on one phrase ends the run; phrases measured before the error are still kept and the SEO alerts after the run still fire. Nothing is charged for a run that hit a provider error.

Common questions

My tracker ran for two days and then stopped. The reason is on the settings row (open GET /api/local-seo/rank-tracker?domain_id=…). Most often the balance ran out: turn it back on after the next monthly allowance lands, or lower the cadence to weekly. The same code path runs every hour, so a run that was skipped waits for the next slot, not the next day.

A phrase moved but I got no alert. A run that measured nothing new writes nothing new; alerts come from the comparison between this run and the last one on each phrase. Phrases that have only one measurement yet are baselines, and the SEO alerts treat them as such.

Can I change the phrases the tracker covers? Save more or fewer phrases on the domain; the tracker takes the oldest ones up to the cap next run. The cap is the plan's, not yours; see Plan caps above.