All documentation

    Rank Tracking

    Rank Pilot AI SEO tracks keyword positions through three connected surfaces — the keyword manager (WebsiteKeywords.tsx), the position history dashboard (RankTracker.tsx) and an ad-hoc lookup tool (SerpChecker.tsx) — backed by the check-ranks and fetch-serp-rankings edge functions.

    Adding and managing keywords

    WebsiteKeywords.tsx is the main keyword workspace for a website. Users add keywords manually (with optional search volume and difficulty), or generate suggestions with the AI keyword generator, which can insert volume/difficulty estimates automatically. Each row shows current and previous position, trend (up/down/stable), search volume and a difficulty bar. Summary cards total tracked keywords, average position and the number improving.

    Google Search Console can be connected per website (GscStatusPanel); when connected, a Sync with Google action calls the syncKeywordsWithGoogle server function to pull live positions, clicks and impressions for tracked keywords and resubmit the sitemap. A recurring sync schedule can also be configured via KeywordSyncSchedule.

    Bulk keyword actions

    Keywords ranking in the top 20 can be bulk-queued for Autopilot content distribution: selecting Queue Top N for Autopilot inserts one row per keyword into autopilot_queue with tool_type: "keywords", source: "user" and status: "pending", tagged for distribution to pages, blog posts and newsletters. From there they're picked up by the queue processor described in the Autopilot documentation. A downloadable SEO report (title, positions, volume, difficulty, trend plus audit and competitor data) can be generated from the same page.

    Rank Tracker (position history)

    RankTracker.tsx, gated behind the rank_monitoring feature, visualises how the top five tracked keywords have moved over time using data from the rank_history table, rendered as a multi-line chart (position on the Y axis, reversed so lower/better positions sit higher). Stat cards summarise total tracked keywords, average position, and counts of keywords trending up or down.

    If the user has configured a Google API key and Custom Search Engine (CX) ID (stored via user_api_keys and checked through the get_user_api_key RPC), a Check Ranks Now button becomes available. This invokes the check-ranks edge function for the current website.

    How check-ranks works

    check-ranks is a per-user, authenticated edge function that:

    1. Retrieves the caller's Google API key and CX ID via a Vault-backed RPC (never exposed directly to the client).
    2. Loads up to 100 tracked keywords for the website.
    3. For each keyword, queries the Google Custom Search API, paging through up to 100 results (10 pages of 10) looking for the tracked domain in the result links, with a short delay between pages to respect rate limits.
    4. Updates each keyword's previous_position, current_position, trend and tracked_at, and appends a row to rank_history for charting.

    Because it depends on a user-supplied Google API key and CX ID, rank checking has an implicit daily quota tied to Google's Custom Search API free/paid tier limits — the free tier is capped at 100 queries per day, so accounts checking many keywords will need a paid Google Cloud key.

    Daily rank checks (cron)

    Scheduled rank refreshes are driven through the platform's cron infrastructure (visible via the admin-cron-status and admin-trigger-cron functions), which periodically re-invokes rank-checking logic across websites so positions stay current without manual clicks, complementing the on-demand Check Ranks Now button.

    SERP Checker

    SerpChecker.tsx is a separate, on-demand lookup tool for checking where a domain ranks for specific keywords without permanently tracking them. Users can enter up to ten keywords individually, paste a bulk list (newline or comma separated), or upload a CSV/TXT file. Checking calls the serp-check edge function with the keyword list and domain, returning a position (or "not found" beyond 100), the source of the data (Google Search Console 28-day average or Custom Search API), and the top 10 organic results with the tracked domain highlighted when it appears.

    Results are ephemeral until explicitly saved — a Save to History action inserts rows into serp_checks, which power a searchable, date-grouped history panel showing position trends between checks (up/down arrows against the previous recorded position for the same keyword).

    fetch-serp-rankings

    A second SERP-fetching function, fetch-serp-rankings, uses the Serper API (SERPER_API_KEY) rather than Google's Custom Search API, keyed by website ID, domain and location (defaulting to United Kingdom). It verifies website ownership before running, then checks tracked keywords for that site — providing an alternative rank-checking backend independent of a user-supplied Google API key.

    Access control

    Rank Tracker is gated behind the rank_monitoring plan feature ("Daily Rank Tracking & Alerts"). The keyword manager, SERP Checker and manual check-ranks calls are otherwise available to any authenticated user with a website, subject to the Google API key requirement for live checks.