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

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
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)
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)
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)
Feature endpoints	Individual server functions for backlinks, rank checks, site audits, and keyword data	src/serverFunctions/backlinks.ts, 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—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

# .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 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) 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:

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), 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) for Docker Compose examples:

# 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) demonstrates the standard pattern:

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) is straightforward:

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:

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), 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
web/content/docs/self-hosting/index.md	Complete self-hosting guide with DataForSEO setup	Self-hosting docs
web/content/docs/self-hosting/docker.md	Docker-specific credential injection instructions	Docker docs
src/shared/selfhost-checks.ts	Runtime validation of DataForSEO configuration	Source
src/shared/billing.ts	Credit calculation and cost markup logic	Source
src/server/mcp/tools/whoami.ts	Credential test command (free, no credits used)	Source
scripts/dataforseo-account-usage.ts	Standalone utility to query DataForSEO account status	Source

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) 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) 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 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) 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.

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