DataForSEO Credit Features in OpenSEO: Complete Guide to API Usage Tracking

OpenSEO tracks every DataForSEO API call through ten distinct credit features defined in src/shared/billing-credit-features.ts, using the mapDataforseoPathToCreditFeature function to map endpoints to billing categories.

OpenSEO, the open-source SEO platform by every-app, implements a granular credit system for DataForSEO API consumption. The CreditFeature type categorizes API usage across keyword research, domain analytics, backlinks, AI optimization, and local SEO—enabling precise billing attribution and usage analytics for each API endpoint.

What Are Credit Features in OpenSEO?

Credit features are billing classifications that group DataForSEO API endpoints by functional domain. The system lives in src/shared/billing-credit-features.ts and provides a single source of truth for how API calls translate to customer costs.

The CreditFeature union type encompasses these ten categories:

Credit Feature	Purpose	DataForSEO Endpoint Pattern
keyword_research	Volume, suggestions, ideas	keywords_data/*, most labs endpoints
domain_overview	Domain-level analytics	Labs endpoints starting with domain_, ranked_keywords, relevant_pages
backlinks	Backlink data retrieval	backlinks/*
site_audit	On-page/site-wide checks	on_page/*
rank_tracking	Rank tracking (reserved)	Future use—currently defaults to site_audit
ai_citations	Brand mentions in LLMs	ai_optimization/*/llm_mentions
ai_prompt_responses	LLM-generated responses	All other ai_optimization/*
local_seo	Maps, local finder, business data	serp/google/maps, serp/google/local_finder, business_data/*
onboarding	First-time user flows	Dedicated onboarding endpoints
agent	SAM self-hosted agent	SAM agent routed calls

How Credit Features Map to DataForSEO Endpoints

The mapDataforseoPathToCreditFeature function implements the routing logic. It normalizes paths to ensure consistent processing:

export function mapDataforseoPathToCreditFeature(path: readonly string[]) {
  const normalized = path[0] === "v3" ? path : ["v3", ...path];
  const module = normalized[1];

  switch (module) {
    case "on_page":          return "site_audit";
    case "backlinks":        return "backlinks";
    case "serp":             return normalized[2] === "google" &&
                               ["maps","local_finder"].includes(normalized[3])
                               ? "local_seo" : "keyword_research";
    case "ai_optimization":  return normalized[2] === "llm_mentions"
                               ? "ai_citations"
                               : "ai_prompt_responses";
    case "business_data":    return "local_seo";
    case "keywords_data":    return "keyword_research";
    case "dataforseo_labs": {
      const endpoint = normalized[3] ?? "";
      return (endpoint.startsWith("domain_") ||
              endpoint === "ranked_keywords" ||
              endpoint === "relevant_pages")
             ? "domain_overview"
             : "keyword_research";
    }
    default:                 return "site_audit";
  }
}

The function handles path normalization explicitly—prefixing v3 when absent—then dispatches based on the top-level module name.

Practical Usage Examples

Mapping a Keyword Research Request

Any endpoint under keywords_data or non-domain-specific labs calls resolve to keyword_research:

import { mapDataforseoPathToCreditFeature } from "@/shared/billing-credit-features";

const path = ["v3", "dataforseo_labs", "google", "related_keywords", "live"];
const feature = mapDataforseoPathToCreditFeature(path);
// feature === "keyword_research"

Mapping a Domain Overview Request

Domain-specific labs endpoints trigger domain_overview:

const domainPath = [
  "v3", "dataforseo_labs", "google", "domain_rank_overview", "live"
];
const domainFeature = mapDataforseoPathToCreditFeature(domainPath);
// domainFeature === "domain_overview"

Displaying Human-Readable Labels

The companion creditFeatureLabel function converts enum values to UI text:

import { creditFeatureLabel, CreditFeature } from "@/shared/billing-credit-features";

function renderFeatureBadge(feature: CreditFeature) {
  return `<span class="badge">${creditFeatureLabel(feature)}</span>`;
}

Where Credit Features Integrate Across OpenSEO

Credit feature logic propagates through several key files:

• src/shared/billing-credit-features.ts — Core type definitions and mapping function
• src/server/lib/dataforseo/client.ts — Client instantiation with credit tracking
• src/server/lib/dataforseo/keyword-metrics.ts — Metric-specific billing imports
• src/server/features/keywords/services/research/research.ts — Research service consumption
• src/server/features/backlinks/services/BacklinksService.ts — Backlink credit attribution

AI Optimization Credit Split

The ai_optimization module receives special handling. The system distinguishes between brand citation lookups (llm_mentions → ai_citations) and direct LLM interactions (ChatGPT, Claude, Gemini → ai_prompt_responses). This separation allows differentiated pricing for passive monitoring versus active AI generation.

Local SEO Aggregation

Two apparently separate DataForSEO modules—serp/google/maps, serp/google/local_finder, and business_data—converge under a single local_seo credit feature. This unification simplifies billing for users focused on local search data regardless of which specific endpoint they invoke.

Summary

• Ten credit features cover all DataForSEO usage: keyword_research, domain_overview, backlinks, site_audit, rank_tracking, ai_citations, ai_prompt_responses, local_seo, onboarding, and agent
• Central mapping in src/shared/billing-credit-features.ts via mapDataforseoPathToCreditFeature
• Path normalization ensures consistent handling whether or not v3 prefix is present
• Module-based dispatch with endpoint-level granularity for dataforseo_labs and ai_optimization
• Integrated tracking across client, service, and UI layers throughout the codebase

Frequently Asked Questions

How does OpenSEO handle DataForSEO API versioning in credit feature mapping?

The mapDataforseoPathToCreditFeature function automatically normalizes paths by prepending v3 if absent. This ensures consistent module extraction regardless of whether callers include the version prefix, future-proofing the billing logic against API version changes.

What's the difference between ai_citations and ai_prompt_responses credits?

ai_citations specifically tracks brand-mention lookups via the llm_mentions endpoint—queries that check where brands appear in LLM training data or outputs. ai_prompt_responses covers all other AI optimization calls: direct interactions with ChatGPT, Claude, Gemini, and similar models for content generation or analysis.

Why does rank_tracking fall back to site_audit credits?

The rank_tracking credit feature exists as a reserved enum value for future dedicated rank-tracking endpoints. Currently, any calls that would map there instead default to site_audit, providing continuity while preserving the semantic structure for eventual separation when specific rank-tracking APIs launch.

Can I extend credit features for custom DataForSEO endpoints?

Yes—modify the CreditFeature union type in src/shared/billing-credit-features.ts and add corresponding cases to mapDataforseoPathToCreditFeature. The switch-based architecture makes extension straightforward, and consuming services throughout OpenSEO will automatically recognize new feature values through the shared type system.

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