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

> Learn how Open SEO uses DataForSEO API methods like serp rankCheck and rankCheckTaskPost for effective rank tracking on desktop and mobile. Implement rank tracking with this guide.

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

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

```typescript
// 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:

```typescript
// 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:

```typescript
// 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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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/*`.