How the Cost of Rank Tracking Is Calculated in OpenSEO

OpenSEO calculates rank tracking costs using a deterministic credit-based algorithm that multiplies keyword count by device types and search depth, then scales by schedule frequency to generate per-check and monthly USD estimates via the estimate_rank_tracker_cost MCP tool.

The every-app/open-seo repository implements this billing logic to abstract DataForSEO pricing into an internal credit system. Understanding how the cost of rank tracking is calculated allows developers to budget accurately for SEO monitoring operations before any live SERP checks execute. The platform requires explicit cost estimation and user approval through the MCP tool interface to prevent unexpected charges.

The Credit-Based Billing Model

OpenSEO uses credits as its internal billing unit, mapping directly to DataForSEO API costs at a fixed conversion rate (typically $0.0005 per credit). When you configure a rank tracker, the system does not charge immediately; instead, it queues checks and estimates consumption. The estimate_rank_tracker_cost tool, defined in src/server/mcp/tools/estimate-rank-tracker-cost.ts, returns three key values:

• costCredits: The nominal queued credits required for the next scheduled check
• costUsd: The dollar equivalent of the credit estimate
• monthlyCostCredits: The projected monthly consumption based on the schedule interval (daily, weekly, or monthly)

This abstraction allows the platform to normalize variable DataForSEO pricing across different markets and search depths into a consistent internal currency.

Core Cost Factors

The calculation algorithm weighs five primary variables to determine the nominal queued credits per scheduled check:

Keyword Volume: Each keyword added to a tracker incurs a base credit cost. In src/server/mcp/tools/add-rank-tracking-keywords.ts (lines 27-38), the documentation specifies that adding keywords requires calculating the "nominal queued credits per scheduled check" before commitment.

Device Multipliers: The cost scales linearly with the number of devices selected. Each device (mobile and desktop) triggers a separate SERP request, doubling the credit consumption when both are selected.

Search Depth: The depth parameter (defaulting to 40 results) determines how many SERP pages the system fetches. Each additional page increment adds a small credit cost to the total.

Schedule Interval: The frequency of checks—manual, daily, weekly, or monthly—directly impacts the monthlyCostCredits projection. A daily schedule multiplies the single-check estimate by 30, while weekly uses 4.3.

Market Location: Certain geographic markets require DataForSEO Labs locations with different base pricing. The chosen market modifies the underlying DataForSEO cost before credit conversion.

The Estimation Implementation

According to the source code in src/server/mcp/tools/estimate-rank-tracker-cost.ts, the estimation logic follows this pattern:

// Calculates: keywords × devices × depth_multiplier × market_modifier
// Returns credits and USD equivalent

The tool reads the tracker configuration from the database, applies the current DataForSEO pricing rates, and returns the estimate. This implementation ensures that the cost of rank tracking is calculated deterministically before any API calls execute.

In src/server/mcp/tools/create-rank-tracker.ts (lines 63-66), the system enforces this pattern by requiring users to call the estimator before adding keywords or initiating live runs. This prevents unexpected charges by establishing an approved credit threshold upfront.

Handling Live vs. Queued Checks

While the estimator provides a maxEstimatedScheduledCheckCredits value, this figure represents the queued task estimate, not an absolute cap. As noted in the error messaging within src/server/features/rank-tracking/services/RankTrackingKeywordService.ts (line 183), live checks that exceed the queued estimate can incur additional credits. The system distinguishes between:

• Queued checks: Scheduled tasks that consume the estimated credits when they run
• Live checks: Immediate executions that may add extra credits if they exceed the pre-calculated estimate

When adding keywords via the MCP tool, you must pass the maxEstimatedScheduledCheckCredits value obtained from the estimator to confirm you accept the projected cost.

Practical Code Examples

To estimate costs before adding keywords:

// Call the estimator with additional keywords
const estimate = await callMcpTool('estimate_rank_tracker_cost', {
  trackerId: 'trk_123',
  additionalKeywordCount: 10
});

// Returns:
// {
//   costCredits: 45,
//   costUsd: 0.0225,
//   monthlyCostCredits: 135
// }

To commit keywords with user-approved limits:

// Add keywords only after estimating and approving the cost
await callMcpTool('add_rank_tracking_keywords', {
  trackerId: 'trk_123',
  keywords: ['seo software', 'rank tracker api'],
  maxEstimatedScheduledCheckCredits: 45  // Approved estimate from previous step
});

These examples demonstrate the standard workflow: calculate the cost of rank tracking operations, obtain user approval through the credit limit parameter, then execute the addition.

Summary

• OpenSEO calculates rank tracking costs using credits that abstract DataForSEO pricing, converting to USD at a fixed rate.
• The estimate_rank_tracker_cost tool in src/server/mcp/tools/estimate-rank-tracker-cost.ts computes costs based on keyword count, device types, search depth, schedule interval, and market location.
• Five core factors determine the nominal queued credits per scheduled check: keywords, devices, depth, schedule, and market.
• Source files including src/server/mcp/tools/create-rank-tracker.ts (lines 63-66) and src/server/mcp/tools/add-rank-tracking-keywords.ts (lines 27-38) enforce estimation before execution.
• The maxEstimatedScheduledCheckCredits parameter ensures users approve costs before keyword addition, though live checks may occasionally exceed these estimates.

Frequently Asked Questions

How does the number of devices affect the cost calculation?

Each selected device (mobile or desktop) triggers a separate DataForSEO SERP request. The cost calculation multiplies the base keyword cost by the number of devices, so tracking both mobile and desktop costs twice as many credits as monitoring a single device.

Is the estimated cost a hard limit that cannot be exceeded?

No. The maxEstimatedScheduledCheckCredits value represents the nominal queued estimate for scheduled checks only. According to the implementation in src/server/features/rank-tracking/services/RankTrackingKeywordService.ts (line 183), live checks or fallback operations can consume additional credits beyond the initial estimate if the queued task fails or timeouts occur.

Where is the credit-to-USD conversion rate defined?

The conversion logic resides within the estimation tools, typically applying a base rate of $0.0005 per credit (though this may vary by configuration). The estimate_rank_tracker_cost tool returns both costCredits and costUsd fields, with the USD value calculated deterministically from the credit count.

What happens if I add keywords without calling the estimator?

The MCP tool workflow in src/server/mcp/tools/add-rank-tracking-keywords.ts requires the maxEstimatedScheduledCheckCredits parameter, which you can only obtain by first calling estimate_rank_tracker_cost. This design prevents accidental cost overruns by forcing cost awareness before keyword addition.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}