Skip to content

Open source alternative to Semrush and Ahrefs

Keep a keyword's previous position when its rank check retry misses, and flag incomplete checks (#917)

Carter Smithb669cbf9aee0
diff --git a/src/client/features/rank-tracking/RankRunAlerts.tsx b/src/client/features/rank-tracking/RankRunAlerts.tsx
new file mode 100644
index 00000000..e3048aaa
--- /dev/null
+++ b/src/client/features/rank-tracking/RankRunAlerts.tsx
@@ -0,0 +1,57 @@
+import { AlertTriangle } from "lucide-react";
+import { Alert, AlertDescription } from "@/client/components/ui/alert";
+import { getStandardErrorMessage } from "@/client/lib/error-messages";
+import type { useRankRunPolling } from "./useRankRunPolling";
+
+/** Warnings about the latest rank check: stale, failed, or incomplete. */
+export function RankRunAlerts({
+ run,
+}: {
+ run: ReturnType<typeof useRankRunPolling>;
+}) {
+ if (!run) return null;
+
+ if (run.maybeStale) {
+ return (
+ <Alert variant="warning">
+ <AlertTriangle />
+ <AlertDescription className="text-foreground">
+ This run may be unresponsive and will be cleaned up automatically.
+ </AlertDescription>
+ </Alert>
+ );
+ }
+
+ if (run.status === "failed") {
+ return (
+ <Alert variant="destructive">
+ <AlertTriangle />
+ <AlertDescription className="text-foreground">
+ <p>
+ <span className="font-medium">Last check failed.</span>{" "}
+ {run.errorMessage &&
+ getStandardErrorMessage(new Error(run.errorMessage))}
+ </p>
+ </AlertDescription>
+ </Alert>
+ );
+ }
+
+ // A completed run only has an error message when some checks failed.
+ if (run.status === "completed" && run.errorMessage) {
+ return (
+ <Alert variant="warning">
+ <AlertTriangle />
+ <AlertDescription className="text-foreground">
+ <p>
+ <span className="font-medium">Your last check was incomplete.</span>{" "}
+ Our search data provider had errors, so some keywords will show
+ their previous position.
+ </p>
+ </AlertDescription>
+ </Alert>
+ );
+ }
+
+ return null;
+}
diff --git a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx
index 3000977e..765f0ddb 100644
--- a/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx
+++ b/src/client/features/rank-tracking/RankTrackingDomainDetail.tsx
@@ -15,9 +15,9 @@ import { QueryState } from "@/client/components/QueryState";
import { SkeletonCard } from "@/client/components/SkeletonPresets";
import { Alert, AlertDescription } from "@/client/components/ui/alert";
import { useHostedPlanGate } from "@/client/features/billing/HostedPlanGate";
-import { getStandardErrorMessage } from "@/client/lib/error-messages";
import { captureClientEvent } from "@/client/lib/posthog";
import { FreePlanAlert } from "./FreePlanAlert";
+import { RankRunAlerts } from "./RankRunAlerts";
import { RankTrackingDetailHeader } from "./RankTrackingDetailHeader";
import { RankTrackingOverview } from "./RankTrackingOverview";
import { RankTrackingTable } from "./RankTrackingTable";
@@ -245,27 +245,7 @@ export function RankTrackingDomainDetail({
</Alert>
)}
- {latestRun?.maybeStale && (
- <Alert variant="warning">
- <AlertTriangle />
- <AlertDescription className="text-foreground">
- This run may be unresponsive and will be cleaned up automatically.
- </AlertDescription>
- </Alert>
- )}
-
- {latestRun?.status === "failed" && (
- <Alert variant="destructive">
- <AlertTriangle />
- <AlertDescription className="text-foreground">
- <p>
- <span className="font-medium">Last check failed.</span>{" "}
- {latestRun.errorMessage &&
- getStandardErrorMessage(new Error(latestRun.errorMessage))}
- </p>
- </AlertDescription>
- </Alert>
- )}
+ <RankRunAlerts run={latestRun} />
<FreePlanAlert visible={planStatus === "free"} />
diff --git a/src/server/workflows/rankCheckPaths.test.ts b/src/server/workflows/rankCheckPaths.test.ts
index 9fc771b0..d55759b9 100644
--- a/src/server/workflows/rankCheckPaths.test.ts
+++ b/src/server/workflows/rankCheckPaths.test.ts
@@ -114,6 +114,32 @@ describe("runLiveCheck", () => {
expect(stats).toMatchObject({ queueTasks: 11, fallbackTasks: 0 });
});
+ it("leaves a pair unchecked when its queued retry doesn't find the domain", async () => {
+ mocks.getSnapshotsForRun.mockResolvedValue([]);
+ mocks.fetchRankCheckTaskResult.mockImplementation(
+ async (task: RankCheckTaskInput) => ({
+ status: "completed",
+ result: {
+ ...task,
+ position: task.keywordId === "kw_0" ? null : 5,
+ url: null,
+ serpFeatures: [],
+ },
+ }),
+ );
+
+ await runManualCheck();
+
+ // The queue round saves every pair except kw_0's not-found.
+ expect(mocks.insertSnapshots).toHaveBeenLastCalledWith(
+ keywords
+ .slice(1)
+ .map((kw): unknown =>
+ expect.objectContaining({ trackingKeywordId: kw.id, position: 5 }),
+ ),
+ );
+ });
+
it("skips the queue when the live endpoint checked every pair", async () => {
mocks.getSnapshotsForRun.mockResolvedValue(
keywords.map((kw) => ({ trackingKeywordId: kw.id, device: "desktop" })),
diff --git a/src/server/workflows/rankCheckPaths.ts b/src/server/workflows/rankCheckPaths.ts
index c5b76bc3..b3bc171f 100644
--- a/src/server/workflows/rankCheckPaths.ts
+++ b/src/server/workflows/rankCheckPaths.ts
@@ -214,9 +214,13 @@ export async function runLiveCheck(
);
// No live fallback here: these pairs already had their live attempt, and a
// second one could take the run past the credits the user approved.
+ // A "not found" from the queue isn't saved either: queued SERPs often miss a
+ // domain the live endpoint finds, so the pair stays "Not checked" and keeps
+ // its previous position instead of reading as lost.
return runQueuedCheck(step, ctx, {
taskInputs: missing,
liveFallback: false,
+ saveNotFound: false,
});
}
@@ -265,6 +269,7 @@ interface CollectRoundOutcome {
async function collectQueuedRound(
ctx: CheckContext,
tasks: PostedRankCheckTask[],
+ saveNotFound: boolean,
): Promise<CollectRoundOutcome> {
const completed: RankCheckResultWithDevice[] = [];
const stillPending: PostedRankCheckTask[] = [];
@@ -300,7 +305,7 @@ async function collectQueuedRound(
// No run error here: a live call records it. That is the live
// fallback, or for a manual retry, the live attempt before the queue.
failed.push(task);
- } else {
+ } else if (saveNotFound || result.value.result.position !== null) {
completed.push({ ...result.value.result, device: task.device });
}
});
@@ -340,7 +345,8 @@ export interface QueuedCheckStats {
* polls task_get for ~15 minutes, writing snapshots incrementally as tasks
* complete. Anything still unfinished after the polling window — plus tasks
* DataForSEO rejected or failed — gets one shot at the live endpoint so a run
- * never hangs on a stuck queue, unless `liveFallback` is false. Billing
+ * never hangs on a stuck queue, unless `liveFallback` is false. With
+ * `saveNotFound` false, a result without the domain isn't saved. Billing
* happens at task_post (and per live-fallback batch).
*/
export async function runQueuedCheck(
@@ -349,7 +355,12 @@ export async function runQueuedCheck(
{
taskInputs = expandToTaskInputs(ctx.keywords, ctx.devices),
liveFallback = true,
- }: { taskInputs?: RankCheckTaskInput[]; liveFallback?: boolean } = {},
+ saveNotFound = true,
+ }: {
+ taskInputs?: RankCheckTaskInput[];
+ liveFallback?: boolean;
+ saveNotFound?: boolean;
+ } = {},
): Promise<QueuedCheckStats> {
// Post all tasks to the queue, <=100 per request, one metered step each.
// A failed chunk must not abort the run — earlier chunks were already
@@ -424,7 +435,7 @@ export async function runQueuedCheck(
step,
`collect-${round}`,
COLLECT_STEP_CONFIG,
- () => collectQueuedRound(ctx, batch),
+ () => collectQueuedRound(ctx, batch, saveNotFound),
);
} catch (error) {
console.warn(`[rank-check] ${ctx.runId} collect-${round} failed:`, error);