# How to Use the DataForSEO API Client in OpenSEO: A Complete Guide

> Learn to use the DataForSEO API client in OpenSEO with this guide. Discover how OpenSEO simplifies API calls with built-in rate limiting and error handling for efficient data retrieval.

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

---

**OpenSEO provides a typed, billing-aware wrapper around the official dataforseo-client SDK, exposing a `createDataforseoClient` factory that instantiates API clients with built-in rate limiting and error handling.**

OpenSEO (`every-app/open-seo`) ships with a thin, typed wrapper around the DataForSEO API located in `src/server/lib/dataforseo/`. This wrapper transforms the official SDK into a billing-contextual client that handles authentication, rate limiting, and response validation automatically. Understanding how to use the DataForSEO API client in OpenSEO enables you to fetch SERP data, keyword metrics, and backlink intelligence within the framework's server-side architecture.

## Initializing the DataForSEO Client

The entry point for all DataForSEO operations is the `createDataforseoClient` factory function exported from [`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts). This function requires a `BillingCustomerContext` object containing the current user's billing plan and quota information.

```typescript
import { createDataforseoClient } from "@/server/lib/dataforseo";

const dataforseo = createDataforseoClient(billingCustomer);

```

The factory returns a typed client object that groups DataForSEO modules under properties like `serp`, `labs`, and `googleAds`. According to the OpenSEO source code, this design allows the client to respect per-plan API quotas while providing full IntelliSense for available endpoints.

## Calling DataForSEO API Endpoints

Once initialized, the client exposes typed methods that mirror the official DataForSEO API structure. Each module provides methods that accept request payloads and return Promise-wrapped responses validated through Zod schemas.

### Fetching SERP Data

The SERP module in [`src/server/lib/dataforseo/serp.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/serp.ts) provides access to live search results. Use the `google.organic.live` method to retrieve real-time organic rankings:

```typescript
const live = await dataforseo.serp.google.organic.live({
  target: "example.com",
  keywords: [{ keyword: "open seo", location_code: 2840 }],
});

```

### Accessing Labs API Features

For keyword research and content intelligence, the Labs API wrapper in [`src/server/lib/dataforseo/labs.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/labs.ts) exposes endpoints like `related_keywords.live`:

```typescript
const related = await dataforseo.labs.google.related_keywords.live({
  keyword: "open seo",
  country: "us",
});

```

### Retrieving Google Ads Metrics

The Google Ads module ([`src/server/lib/dataforseo/google-ads.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/google-ads.ts)) provides CPC and search volume data through the `keywords_data.get` method:

```typescript
const ads = await dataforseo.googleAds.keywords_data.get({
  keyword: "open seo",
  country: "us",
});

```

## Error Handling and Response Validation

All API calls pass through the envelope helper located in [`src/server/lib/dataforseo/envelope.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/envelope.ts). The `wrapAsync` function translates DataForSEO error objects into a consistent `{ errorCode, message }` shape and throws typed exceptions when `status_code !== 200`. This ensures that downstream code receives standardized error objects rather than raw SDK responses.

## Rate Limiting and Billing Awareness

The wrapper implements billing-aware throttling using constants defined in [`src/server/lib/dataforseo/shared.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/shared.ts). The `MAX_TASKS_PER_POST` value determines batch sizes to prevent hitting API rate limits. Because the `createDataforseoClient` function receives the user's `BillingCustomerContext`, the client automatically adjusts request volume based on the specific plan's quota limits.

## Real-World Usage in Workflows

OpenSEO's production workflows demonstrate the typical server-side pattern. In [`src/server/workflows/RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/src/server/workflows/RankCheckWorkflow.ts), the client is instantiated per-request and passed to service functions:

```typescript
const client = createDataforseoClient(billingCustomer);
const results = await client.serp.google.organic.live(...);

```

Complete server function example:

```typescript
import { createDataforseoClient } from "@/server/lib/dataforseo";

export async function getKeywordInsights(billingCustomer) {
  const dfs = createDataforseoClient(billingCustomer);

  // Fetch live SERP data
  const serp = await dfs.serp.google.organic.live({
    target: "example.com",
    keywords: [{ keyword: "open seo", location_code: 2840 }],
  });

  // Fetch related keywords from Labs API
  const related = await dfs.labs.google.related_keywords.live({
    keyword: "open seo",
    country: "us",
  });

  // Fetch Google Ads volume/CPC
  const ads = await dfs.googleAds.keywords_data.get({
    keyword: "open seo",
    country: "us",
  });

  return { serp, related, ads };
}

```

For React Server Components or TanStack Server Functions:

```typescript
import { createDataforseoClient } from "@/server/lib/dataforseo";
import { getBillingCustomer } from "@/server/lib/auth-session";

export async function fetchSerpForPage(pageUrl: string) {
  const billingCustomer = await getBillingCustomer();
  const dfs = createDataforseoClient(billingCustomer);

  const response = await dfs.serp.google.organic.live({
    target: pageUrl,
    keywords: [{ keyword: "next-js seo", location_code: 2840 }],
  });

  return response;
}

```

## Summary

- **Factory Pattern**: Import `createDataforseoClient` from `@/server/lib/dataforseo` and pass a `BillingCustomerContext` to instantiate the client.
- **Typed Modules**: Access SERP, Labs, and Google Ads endpoints through typed properties like `serp.google.organic.live`.
- **Automatic Validation**: All responses pass through Zod validation and error normalization via [`src/server/lib/dataforseo/envelope.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/envelope.ts).
- **Quota Management**: The client respects billing plan limits using `MAX_TASKS_PER_POST` from [`src/server/lib/dataforseo/shared.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/shared.ts) to batch requests appropriately.
- **Server-First Design**: Initialize the client within server functions or workflows like [`RankCheckWorkflow.ts`](https://github.com/every-app/open-seo/blob/main/RankCheckWorkflow.ts), never exposing credentials to the client bundle.

## Frequently Asked Questions

### What is the DataForSEO API client in OpenSEO?

The DataForSEO API client in OpenSEO is a typed wrapper around the official `dataforseo-client` SDK located in `src/server/lib/dataforseo/`. It provides a factory function `createDataforseoClient` that creates billing-aware API instances with built-in rate limiting, error handling, and Zod validation for all DataForSEO endpoints including SERP, Labs, and Google Ads data.

### How does the OpenSEO wrapper handle API rate limits?

The wrapper respects rate limits through the `MAX_TASKS_PER_POST` constant defined in [`src/server/lib/dataforseo/shared.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/shared.ts). When the `createDataforseoClient` function receives a `BillingCustomerContext`, it uses the plan's quota information to batch tasks appropriately, preventing requests from exceeding the user's API allowance or DataForSEO's posting limits.

### Which DataForSEO endpoints are available through the OpenSEO client?

As implemented in every-app/open-seo, the wrapper exposes three main modules: **SERP** ([`src/server/lib/dataforseo/serp.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/serp.ts)) for search results, **Labs** ([`src/server/lib/dataforseo/labs.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/labs.ts)) for keyword research and content ideas, and **Google Ads** ([`src/server/lib/dataforseo/google-ads.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/google-ads.ts)) for CPC and volume data. Each module provides typed methods that correspond to DataForSEO's live API endpoints.

### How are errors handled when calling DataForSEO endpoints?

All API calls are wrapped by the envelope helper in [`src/server/lib/dataforseo/envelope.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/envelope.ts). The `wrapAsync` function intercepts responses, validates them against expected schemas using Zod, and translates DataForSEO error objects into standardized `{ errorCode, message }` shapes. When the API returns a `status_code !== 200`, the wrapper throws a typed exception that can be caught and handled by your application logic.