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

> Discover DataForSEO credit features in OpenSEO and master API usage tracking. Learn how OpenSEO maps DataForSEO endpoints to billing categories for precise credit management. Read the complete guide.

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

---

**OpenSEO tracks every DataForSEO API call through ten distinct credit features defined in [`src/shared/billing-credit-features.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

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

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

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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/shared/billing-credit-features.ts)** — Core type definitions and mapping function
- **[`src/server/lib/dataforseo/client.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.ts)** — Client instantiation with credit tracking
- **[`src/server/lib/dataforseo/keyword-metrics.ts`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/keyword-metrics.ts)** — Metric-specific billing imports
- **[`src/server/features/keywords/services/research/research.ts`](https://github.com/every-app/open-seo/blob/main/src/server/features/keywords/services/research/research.ts)** — Research service consumption
- **[`src/server/features/backlinks/services/BacklinksService.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.