# How OpenSEO Rank Tracking Works: Architecture and Cost Breakdown

> Discover how OpenSEO rank tracking works with its dual DataForSEO API integration. Understand the cost savings of queued vs live checks for scheduled monitoring and on-demand lookups.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: architecture
- Published: 2026-08-09

---

**OpenSEO's rank tracking system uses a dual-method DataForSEO API integration with live and queued endpoints, where queued checks cost ~75% less and are used for scheduled monitoring while live checks power on-demand lookups.**

OpenSEO is an open-source SEO platform that lets users monitor search engine positions without surprise bills. This article explains how its rank tracking engine calculates costs, schedules checks, and optimizes spend—based on the actual implementation in `every-app/open-seo`.

---

## DataForSEO Integration: Live vs. Queued Methods

At the heart of OpenSEO's rank tracking is the **DataForSEO API**, accessed through two distinct patterns defined in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts).

**Live requests** hit an instant endpoint for immediate results. These power manual "Check now" actions but carry premium pricing.

**Queued requests** submit to a task queue processed asynchronously. Scheduled daily, weekly, or monthly checks use this method exclusively, delivering roughly **3× cost savings** per SERP page.

The choice between methods is not automatic—it's intentional. As implemented in [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts), the system routes user-initiated checks to live endpoints and background jobs to the queue.

---

## Cost Calculation: From USD to Credits

OpenSEO converts raw API costs into predictable **billing credits** through a transparent formula in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts).

### Base API Pricing (per 10-result page)

| Method | First Page | Additional Pages |
|--------|-----------|------------------|
| Live | $0.002 | $0.0015 (25% discount) |
| Queued | $0.0006 | $0.00045 (25% discount) |

The `costPerSerpAtDepth(depth, method)` helper converts any result depth into a USD cost, applying the 75% tier automatically after the first page.

### Full Cost Estimation Pipeline

The `estimateRankCheckCredits()` function combines multiple factors:

```ts
export function estimateRankCheckCredits(
  keywordCount: number,
  devices: RankTrackingConfig["devices"],
  depth: number,
  method: RankCheckMethod,
) {
  const totalChecks = keywordCount * devicesCount(devices);
  const costUsd = roundUsdForBilling(
    totalChecks * costPerSerpAtDepth(depth, method) * SEO_DATA_COST_MARKUP,
  );
  const costCredits = Math.ceil(costUsd * AUTUMN_SEO_DATA_CREDITS_PER_USD);
  return { costUsd, costCredits };
}

```

**How the calculation works:**
- `keywordCount × devicesCount(devices)` — total SERP calls (desktop, mobile, or both)
- `costPerSerpAtDepth(depth, method)` — per-call cost based on result depth
- `SEO_DATA_COST_MARKUP` — platform margin added in [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)
- `roundUsdForBilling()` — standardized rounding
- `AUTUMN_SEO_DATA_CREDITS_PER_USD` — final conversion to internal credits

---

## Scheduling Logic and Drift Prevention

OpenSEO's `computeNextCheckAt()` function in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts) handles recurring checks with two key design decisions:

**Interval-based progression** — The function takes an optional `previousNextCheckAt` parameter to prevent schedule drift when jobs run late. Rather than calculating from "now," it advances from the prior scheduled time.

**Load distribution** — Monthly schedules randomize execution between 04:00–09:00 UTC to prevent thundering-herd problems against the DataForSEO queue.

```ts
export function computeNextCheckAt(
  interval: ScheduledRankTrackingInterval,
  previousNextCheckAt?: string | null,
): string {
  const now = Date.now();
  // Logic handles daily (+1 day), weekly (+7 days), or monthly advancement
  // with randomized hour selection for monthly intervals
}

```

Available intervals: `daily`, `weekly`, `monthly`, or `manual` (no automatic scheduling).

---

## Cost Factors and Optimization Strategies

Understanding how OpenSEO calculates rank tracking costs helps users minimize spend without sacrificing data quality.

### Primary Cost Drivers

- **Method selection** — Queued checks reduce per-page costs from $0.002 to $0.0006 (live vs. queued first page)
- **Depth configuration** — Every 10 additional results adds 75% of the base page cost
- **Device coverage** — Selecting `both` devices doubles check volume versus `desktop` or `mobile` alone
- **Keyword volume** — Linear multiplier across all other factors
- **Schedule frequency** — More frequent checks accumulate more queued requests

### Practical Cost Example

```ts
import { estimateRankCheckCredits } from "@/shared/rank-tracking";

// Weekly queued monitoring: 250 keywords, both devices, 30 results deep
const { costUsd, costCredits } = estimateRankCheckCredits(
  250,
  "both",
  30,
  "queued"
);
console.log(`Weekly queued run → $${costUsd} ≈ ${costCredits} credits`);
// Output: Weekly queued run → $0.27 ≈ 27 credits

```

For the same configuration with **live** method and **100-result depth**, costs scale to approximately **$1.35 and 135 credits**—a 5× increase for real-time data and deeper rankings.

---

## File Architecture and Implementation

| File | Responsibility |
|------|---------------|
| [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts) | Cost constants, `estimateRankCheckCredits`, `computeNextCheckAt`, device/depth helpers |
| [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) | `AUTUMN_SEO_DATA_CREDITS_PER_USD`, `SEO_DATA_COST_MARKUP`, rounding utilities |
| [`src/serverFunctions/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-tracking.ts) | API endpoints exposing cost estimation to frontend |
| [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts) | Worker orchestration selecting live or queued execution |
| [`src/client/features/rank-tracking/rankTrackingScorecards.tsx`](https://github.com/every-app/open-seo/blob/main/src/client/features/rank-tracking/rankTrackingScorecards.tsx) | UI displaying live cost estimates and schedule status |

This separation lets users preview exact credit consumption before enabling tracking, with all calculations server-side to prevent manipulation.

---

## Summary

- **OpenSEO rank tracking** uses DataForSEO's live endpoint for manual checks and queued endpoint for scheduled monitoring, with queued requests costing ~75% less per page.
- **Cost estimation** follows a deterministic formula: keyword count × devices × depth-adjusted SERP cost × markup, converted to credits via `estimateRankCheckCredits()`.
- **Scheduling** prevents drift through interval-based advancement and distributes monthly load across early-morning UTC hours.
- **Optimization** comes from using queued methods, limiting depth to necessary results, and selecting device coverage strategically.

---

## Frequently Asked Questions

### How much does OpenSEO charge per keyword check?

OpenSEO passes through DataForSEO costs with markup. For a single keyword at default 10-result depth: **$0.002 USD live** or **$0.0006 USD queued** per device. Both devices doubles this. Deeper results add 75% of first-page cost per additional page. Final prices appear in credits via `estimateRankCheckCredits()`.

### Why are queued checks cheaper than live checks in OpenSEO?

DataForSEO prices queued requests lower because they enter an asynchronous processing pool rather than reserving immediate compute. OpenSEO routes all scheduled monitoring through this cheaper channel, reserving live requests for user-triggered actions. The 3× cost difference reflects this infrastructure efficiency.

### Can I predict my rank tracking costs before enabling monitoring?

Yes. The `estimateRankCheckCredits()` function in [`src/shared/rank-tracking.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/rank-tracking.ts) returns exact USD and credit costs for any configuration. The UI component [`rankTrackingScorecards.tsx`](https://github.com/every-app/open-seo/blob/main/rankTrackingScorecards.tsx) surfaces this pre-flight so users never exceed budgets unexpectedly.

### What happens if a scheduled rank check runs late?

The `computeNextCheckAt()` function accepts `previousNextCheckAt` to advance from the original scheduled time rather than "now," preventing schedule drift. Monthly jobs additionally randomize their hour between 04:00–09:00 UTC to maintain API quota health.