# How to Integrate DataForSEO with OpenSEO: Self-Hosted and Cloud Setup Guide

> Integrate DataForSEO with OpenSEO effortlessly. Set your DATAFORSEO API key and verify connectivity. Works seamlessly for both cloud and self-hosted setups. Get started now.

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

---

**Set your `DATAFORSEO_API_KEY` environment variable with a base64-encoded `email:password` credential, then verify connectivity with the built-in `whoami` command—no additional configuration required for either cloud or self-hosted deployments.**

OpenSEO relies on DataForSEO as its primary data provider for keyword research, rank tracking, backlink analysis, and AI-search visibility metrics. The integration is baked into the codebase and activates automatically once you supply valid API credentials. This guide walks you through the architecture, configuration steps, and key source files that power the connection.

## DataForSEO Integration Architecture

OpenSEO abstracts DataForSEO's task-based API behind a unified server interface. When you request SEO data—whether through the web UI or API—the backend constructs a task envelope, posts it to DataForSEO's endpoint, polls the queue until completion, and returns normalized results.

| Component | Purpose | Location in Codebase |
|-----------|---------|----------------------|
| **DataForSEO API client** | Handles authentication, request signing, and task polling | [`src/lib/dataforseo-client.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts) |
| **Environment validation** | Ensures `DATAFORSEO_API_KEY` is present and properly encoded before any paid request | [[`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) |
| **Credit pooling** | Aggregates usage for hosted customers; passes through costs for self-hosted users | [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) |
| **Cost markup** | Applies 28% markup to raw DataForSEO rates in the hosted service | [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) |
| **Feature endpoints** | Individual server functions for backlinks, rank checks, site audits, and keyword data | [`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts), [`src/serverFunctions/rank-check.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/rank-check.ts), etc. |

The architecture treats DataForSEO as a metered utility. Hosted users purchase credits through OpenSEO's billing system; self-hosted users pay DataForSEO directly at published rates.

## Prerequisites: DataForSEO Account Setup

Before integrating with OpenSEO, you need active DataForSEO credentials:

1. **Create a DataForSEO account** at [dataforseo.com](https://dataforseo.com)—new accounts receive $1 in free credits for testing.
2. **Locate your API credentials** in the DataForSEO dashboard. The API uses HTTP Basic Auth with your email as username and password as the secret.
3. **Encode your credentials** as base64: `echo -n 'your@email.com:yourpassword' | base64`

## Configuring the DataForSEO API Key

### Self-Hosted Installation

For self-hosted deployments, configure the API key via environment variables:

**Step 1: Edit your `.env` file**

```text

# .env

DATAFORSEO_API_KEY=base64:YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz

```

The `base64:` prefix is required. The encoded string represents `email:password` without additional headers or metadata. See [`.env.example`](https://github.com/every-app/open-seo/blob/main/.env.example) for the complete template.

**Step 2: Validate the configuration**

OpenSEO includes a built-in check that runs before any paid DataForSEO request. The validation logic in [[`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) verifies:

- The `DATAFORSEO_API_KEY` variable exists
- It contains a valid base64-encoded string
- The decoded value follows `email:password` format

**Step 3: Test connectivity without spending credits**

Run the `whoami` command to confirm your credentials work:

```bash
npm run cli whoami

```

This queries [[`src/server/mcp/tools/whoami.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts), which calls DataForSEO's account info endpoint—a free operation that returns your remaining balance and account status.

### Docker-Based Deployment

For containerized setups, inject the API key at runtime. Refer to [[`web/content/docs/self-hosting/docker.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md)](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md) for Docker Compose examples:

```yaml

# docker-compose.yml

services:
  app:
    environment:
      - DATAFORSEO_API_KEY=base64:YWJjQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz

```

The Docker-specific documentation covers volume mounts, secret management, and multi-environment configurations.

### Cloud/Hosted Deployment

If you use OpenSEO's managed service, you do not configure DataForSEO credentials directly. Instead, you purchase credits through the built-in billing system. OpenSEO manages the underlying DataForSEO account, applies the 28% markup, and handles task queuing transparently.

## Using DataForSEO Features in OpenSEO

Once configured, all data-dependent features automatically route to DataForSEO. Here's how typical operations flow through the system:

### Example: Backlink Analysis

The backlink checker in [[`src/serverFunctions/backlinks.ts`](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts)](https://github.com/every-app/open-seo/blob/main/src/serverFunctions/backlinks.ts) demonstrates the standard pattern:

```typescript
import { dataForSeoClient } from '../lib/dataforseo-client';

export async function getBacklinks(projectId: string, domain: string) {
  // Build task envelope per DataForSEO spec
  const task = await dataForSeoClient.post('/backlinks/live', {
    target: domain,
    include_subdomains: true,
    limit: 100
  });
  
  // Poll task queue until completion
  const result = await pollTaskCompletion(task.id);
  
  // Transform and return normalized data
  return normalizeBacklinkData(result);
}

```

Error handling follows DataForSEO's conventions: HTTP 200 responses contain task-specific status codes (e.g., `20000` for success, `40202` for insufficient credits). These are propagated to the client with appropriate messaging.

### Example: Cost Calculation

For hosted deployments, OpenSEO converts raw DataForSEO costs to credit deductions. The markup logic in [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) is straightforward:

```typescript
export function rawToHostedCost(rawUsd: number): number {
  const MARKUP = 1.28; // 28% OpenSEO markup
  return Math.round(rawUsd * MARKUP * 100) / 100;
}

```

A $0.50 DataForSEO backlink check costs the hosted user $0.64 in credits.

## Monitoring DataForSEO Usage

### Self-Hosted Monitoring

Track your direct DataForSEO spending with the included utility script:

```bash
npx tsx scripts/dataforseo-account-usage.ts

```

This queries [[`scripts/dataforseo-account-usage.ts`](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts)](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts), which fetches:

- Current account balance
- Daily spending rate
- Active task queue status
- Historical usage by endpoint

### Hosted Credit Dashboard

Cloud users view real-time credit balances and per-feature costs in the OpenSEO web interface. The credit pool aggregates across all DataForSEO endpoints and applies the standard markup automatically.

## Key Configuration Files Reference

| File | Purpose | Documentation Link |
|------|---------|------------------|
| `.env.example` | Template for all environment variables including `DATAFORSEO_API_KEY` | [`.env.example`](https://github.com/every-app/open-seo/blob/main/.env.example) |
| [`web/content/docs/self-hosting/index.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/index.md) | Complete self-hosting guide with DataForSEO setup | [Self-hosting docs](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/index.md) |
| [`web/content/docs/self-hosting/docker.md`](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md) | Docker-specific credential injection instructions | [Docker docs](https://github.com/every-app/open-seo/blob/main/web/content/docs/self-hosting/docker.md) |
| [`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) | Runtime validation of DataForSEO configuration | [Source](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) |
| [`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) | Credit calculation and cost markup logic | [Source](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) |
| [`src/server/mcp/tools/whoami.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts) | Credential test command (free, no credits used) | [Source](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts) |
| [`scripts/dataforseo-account-usage.ts`](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts) | Standalone utility to query DataForSEO account status | [Source](https://github.com/every-app/open-seo/blob/main/scripts/dataforseo-account-usage.ts) |

## Summary

- **DataForSEO powers all SEO data in OpenSEO**—keyword research, backlinks, rank tracking, and site audits require valid API credentials.
- **Self-hosted users** set `DATAFORSEO_API_KEY` as a base64-encoded `email:password` string in their environment, then verify with `npm run cli whoami`.
- **Hosted users** purchase credits through OpenSEO's billing system; DataForSEO credentials are managed transparently.
- **Cost transparency** is built-in: self-hosted users pay DataForSEO directly at published rates, while hosted users see a 28% markup applied automatically.
- **Validation and monitoring tools** are included in the codebase to prevent misconfiguration and track spending.

## Frequently Asked Questions

### What format should my DataForSEO API key use?

The `DATAFORSEO_API_KEY` environment variable must contain `base64:` followed by the base64-encoded string of your DataForSEO email and password separated by a colon. For example: `base64:dXNlckBleGFtcGxlLmNvbTpwYXNzd29yZA==`. The [[`src/shared/selfhost-checks.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/selfhost-checks.ts) module validates this format at runtime and throws a clear error if the credential is malformed or missing.

### Can I test my DataForSEO integration without spending credits?

Yes. The `whoami` command implemented in [[`src/server/mcp/tools/whoami.ts`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts)](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts) queries DataForSEO's account information endpoint, which is free and returns your authenticated user details and remaining balance. Run `npm run cli whoami` after setting your API key to confirm connectivity.

### How does OpenSEO handle DataForSEO errors and rate limits?

OpenSEO propagates DataForSEO's task-level status codes directly. Successful tasks return `20000`; credit exhaustion returns `40202`; invalid parameters return `40000`-range codes. The client implementation in [`src/lib/dataforseo-client.ts`](https://github.com/every-app/open-seo/blob/main/src/lib/dataforseo-client.ts) handles automatic retries for transient failures and implements exponential backoff for rate limit responses (`429` HTTP status).

### What's the difference between self-hosted and hosted DataForSEO costs?

Self-hosted deployments pass DataForSEO costs through directly—you pay DataForSEO's published USD rates. The hosted service in [[`src/shared/billing.ts`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts)](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts) applies a 28% markup (multiplier of 1.28) to cover infrastructure, support, and credit pooling overhead. Both approaches use identical underlying API calls and data quality.