DataForSEO API Methods for Rank Tracking in Open SEO: Implementation Guide

Open SEO utilizes three specific DataForSEO API methods—client.serp.rankCheck for live requests, client.serp.rankCheckTaskPost for queued tasks, and fetchRankCheckTaskResult for retrieving results—to execute comprehensive rank tracking across desktop and mobile devices.

The Open SEO repository integrates with the DataForSEO API to provide robust rank tracking capabilities. By leveraging both live endpoints and queued task systems, the application balances real-time data retrieval with cost-effective batch processing. Understanding these DataForSEO API methods for rank tracking is essential for developers extending or debugging the SERP monitoring functionality.

The Three Core DataForSEO API Methods for Rank Tracking

Open SEO implements a dual-path architecture for rank tracking, utilizing both immediate execution and asynchronous queue processing. The integration relies on three distinct API interactions defined in the DataForSEO client wrapper and consumed within the workflow layers.

serp.rankCheck (Live Endpoint)

The serp.rankCheck method executes immediate SERP requests for specific keyword and device combinations. This live endpoint returns ranking results synchronously, making it ideal for manual checks and fallback scenarios when queued tasks fail.

In src/server/workflows/rankCheckPaths.ts (lines 84–100), the checkBatchLive function invokes this method within the rank-checking workflow. The function passes parameters including keyword, keywordId, locationCode, languageCode, locationName, device (desktop or mobile), targetDomain, and depth (typically 10 for first-page results).

serp.rankCheckTaskPost (Queued Tasks)

For scheduled, high-volume checking, Open SEO uses serp.rankCheckTaskPost to submit tasks to DataForSEO's standard-priority queue. Located in src/server/workflows/rankCheckPaths.ts (lines 93–109), the runQueuedCheck function batches up to 100 tasks per request, significantly reducing API costs compared to live endpoints.

This method posts keyword/device pairs asynchronously, allowing the system to retrieve results later via polling. The queued approach is the default for automated rank tracking workflows due to its cost efficiency.

fetchRankCheckTaskResult (Task Retrieval)

The fetchRankCheckTaskResult helper wraps DataForSEO's task_get endpoint to retrieve results from previously posted queued tasks. Implemented in src/server/workflows/rankCheckPaths.ts (lines 151–162), this function polls repeatedly until tasks reach a terminal status of completed, failed, or until the polling window expires.

This method handles the asynchronous nature of queued SERP requests, parsing the response to extract ranking data or failure states for each keyword tracked.

Implementation Details and Code Examples

Executing Live Rank Checks

Use the live endpoint when you need immediate results or when implementing fallback logic for failed queue tasks:

// Direct live rank check for immediate results
const liveResult = await client.serp.rankCheck({
  keyword: "open source seo tools",
  keywordId: "uuid-123",           // Internal database identifier
  locationCode: 2840,               // DataForSEO location code (e.g., USA)
  languageCode: "en",               // ISO language code
  locationName: "United States",    // Human-readable location
  device: "desktop",                // or "mobile"
  targetDomain: "example.com",      // Domain being monitored
  depth: 10,                        // Number of SERP results to fetch
});

Posting Batched Queue Tasks

For bulk operations, batch multiple keywords into a single queued request:

// Queue up to 100 tasks in a single API call
await client.serp.rankCheckTaskPost({
  tasks: [
    { 
      keyword: "seo software", 
      keywordId: "uuid-456", 
      device: "desktop" 
    },
    { 
      keyword: "seo software", 
      keywordId: "uuid-457", 
      device: "mobile" 
    },
    // ... additional tasks up to 100 per request
  ],
  locationCode: 2840,
  languageCode: "en",
  locationName: "United States",
  depth: 10,
  targetDomain: "example.com",
});

Polling for Task Completion

Retrieve results from queued tasks using the polling wrapper:

// Poll for specific task completion
const result = await fetchRankCheckTaskResult({
  taskId: "task-abc-123",           // ID returned from rankCheckTaskPost
  keywordId: "uuid-456",
  keyword: "seo software",
  targetDomain: "example.com",
});

// Handle response status
if (result.status === "completed") {
  // Process result.result containing ranking data
} else if (result.status === "pending") {
  // Continue polling in next iteration
} else if (result.status === "failed") {
  // Trigger fallback to live endpoint or error handling
}

Workflow Architecture and Key Files

The rank tracking system spans several critical files within the codebase:

• src/server/workflows/rankCheckPaths.ts – Contains the primary orchestration logic, including checkBatchLive and runQueuedCheck functions that invoke the DataForSEO methods directly.

• src/shared/rank-tracking.ts – Defines cost constants and helper functions for estimating DataForSEO credit consumption, enabling budget-aware batching decisions.

• src/server/lib/dataforseo/* – Houses the HTTP client wrapper that exposes client.serp.rankCheck, client.serp.rankCheckTaskPost, and the fetchRankCheckTaskResult utility.

• src/server/mcp/tools/* – Provides high-level tool interfaces used by the UI layer, ultimately delegating to the workflow methods described above.

Summary

• Live checks via client.serp.rankCheck provide immediate SERP data for manual queries and fallback scenarios, implemented in src/server/workflows/rankCheckPaths.ts lines 84–100.
• Queued processing via client.serp.rankCheckTaskPost enables cost-effective bulk submission of up to 100 tasks per request, found in lines 93–109 of the same file.
• Result retrieval via fetchRankCheckTaskResult wraps the DataForSEO task_get endpoint to poll for completed queued tasks, located at lines 151–162.
• The architecture balances real-time responsiveness with economic efficiency by utilizing both synchronous and asynchronous DataForSEO API pathways.

Frequently Asked Questions

What is the difference between live and queued rank checks in Open SEO?

Live checks execute immediately using client.serp.rankCheck and return results synchronously, making them suitable for on-demand queries but more expensive per request. Queued checks use client.serp.rankCheckTaskPost to submit tasks to DataForSEO's processing queue, which is significantly cheaper but requires asynchronous polling via fetchRankCheckTaskResult to retrieve results later.

How does Open SEO handle failed DataForSEO tasks?

When fetchRankCheckTaskResult returns a status of "failed" or when a queued task exceeds the polling timeout window, the workflow in src/server/workflows/rankCheckPaths.ts triggers a fallback mechanism. The system automatically retries the specific keyword/device combination using the live client.serp.rankCheck endpoint to ensure rank data is still collected despite the queue failure.

Where is the DataForSEO client configured in the Open SEO repository?

The DataForSEO client implementation resides in src/server/lib/dataforseo/*, which exports a configured client instance exposing the serp namespace methods. This wrapper handles authentication, request formatting, and response parsing. The rankCheckPaths.ts workflow imports this client through a context object (ctx.client) to execute API calls.

What are the rate limits and batch size constraints for DataForSEO operations?

According to the implementation in src/server/workflows/rankCheckPaths.ts, Open SEO batches a maximum of 100 tasks per rankCheckTaskPost request to comply with DataForSEO's queue limits. The polling mechanism in fetchRankCheckTaskResult implements retry logic with appropriate delays to respect DataForSEO's rate limits for the task_get endpoint, though specific rate limit values are managed by the client configuration in src/server/lib/dataforseo/*.

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