How OpenSEO Tracks API Costs Using DataForSEO’s Billing Classification

OpenSEO treats every DataForSEO request as a credit-consuming operation that debits a shared usage-credit pool, mapping API endpoints to specific feature classifications and applying platform markup before deducting from the SEO data balance.

OpenSEO implements a sophisticated billing layer that transforms raw DataForSEO API costs into a credit-based accounting system for hosted deployments. By converting USD costs into platform credits and attributing usage to high-level features like keyword research or site audits, the every-app/open-seo repository provides granular cost visibility while maintaining a unified balance across all SEO data operations.

Credit Feature Mapping

OpenSEO attributes every DataForSEO call to a specific product feature using the mapDataforseoPathToCreditFeature function. This mapping logic resides in src/shared/billing-credit-features.ts and converts API response paths into canonical feature identifiers used for analytics and cost tracking.

When a DataForSEO endpoint returns data, the system extracts the path array from the response and maps it to a credit feature. For example, a request to the Google related keywords endpoint translates to the keyword_research classification:

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

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

This classification ensures that costs appear categorized correctly in billing dashboards, distinguishing between keyword research, backlink analysis, site audits, and other SEO features.

Credit Pool and Cost Conversion

The core billing constants for OpenSEO’s DataForSEO integration live in src/shared/billing.ts. This file defines three critical values that govern cost calculation:

• AUTUMN_SEO_DATA_BALANCE_FEATURE_ID: The identifier for the shared SEO data credit pool
• AUTUMN_SEO_DATA_CREDITS_PER_USD: The conversion rate translating raw USD costs into platform credits
• SEO_DATA_COST_MARKUP: The platform markup percentage applied to hosted deployments

When DataForSEO returns a raw USD cost, OpenSEO executes a three-step conversion process:

1. Convert USD to credits: Multiply the raw cost by AUTUMN_SEO_DATA_CREDITS_PER_USD
2. Apply markup: Use applyBillingMarkupUsd to calculate the final billed amount
3. Deduct balance: Subtract the credit equivalent from the organization's SEO data balance

import { applyBillingMarkupUsd } from "@/shared/billing";

const rawUsd = 0.042; // cost reported by DataForSEO
const billedUsd = applyBillingMarkupUsd(rawUsd);
// billedUsd ≈ 0.054 (rounded)

Hosted customers see the marked-up amount in their billing, while self-hosted installations bypass this logic entirely and pay DataForSEO directly at raw rates.

Persisting Usage Events

Hosted deployments report every credit deduction to the Autumn billing service, creating an immutable ledger of SEO data spending. The src/serverFunctions/billing.ts file implements getBillingUsageEvents, which pulls historic usage data from Autumn's /v1/events.list endpoint.

This function queries for events tagged with either usage_credits or topup_credits features, returning a chronological record of all balance changes:

import { getBillingUsageEvents } from "@/serverFunctions/billing";

await getBillingUsageEvents({
  data: { start: Date.now() - 7 * 24 * 60 * 60_000, end: Date.now() },
  context: { organizationId: "org_12345" },
});
// Returns an array of events, each containing the credit amount spent per feature.

These events enable real-time balance monitoring and detailed cost attribution across teams or projects.

Self-Hosted vs. Hosted Billing Models

OpenSEO supports two distinct billing architectures depending on deployment mode.

Self-Hosted Installations communicate directly with DataForSEO using personal API credentials. These deployments pay DataForSEO directly and view raw USD costs without platform markup or credit conversion. The credit pool logic remains dormant in self-hosted contexts.

Hosted Deployments utilize the full credit system described above. Organizations purchase credits in advance, and each successful DataForSEO API call deducts from the shared balance. To check remaining credits programmatically, hosted implementations use the checkBalance utility from src/server/mcp/tools/whoami.ts:

import { checkBalance } from "@/server/mcp/tools/whoami";
import { AUTUMN_SEO_DATA_BALANCE_FEATURE_ID } from "@/shared/billing";

const remaining = await checkBalance(
  AUTUMN_SEO_DATA_BALANCE_FEATURE_ID,
  auth.organizationId,
);
// `remaining` is the number of credits the user can still spend.

The test suite in src/server/lib/dataforseo/client.test.ts verifies that credit deductions record correctly across both deployment contexts, ensuring billing accuracy for all DataForSEO operations.

Summary

• Feature Mapping: The mapDataforseoPathToCreditFeature function in src/shared/billing-credit-features.ts categorizes every DataForSEO endpoint into high-level features like keyword research or backlink analysis.

• Credit Conversion: Constants in src/shared/billing.ts define the conversion rate (AUTUMN_SEO_DATA_CREDITS_PER_USD) and markup logic (applyBillingMarkupUsd) that transform raw DataForSEO costs into platform credits.

• Event Tracking: The getBillingUsageEvents function retrieves historic credit consumption from the Autumn billing service, providing a complete audit trail of SEO data spending.

• Deployment Flexibility: Self-hosted users pay DataForSEO directly at raw rates, while hosted users operate within a credit-pool system with automatic markup and balance management.

Frequently Asked Questions

How does OpenSEO classify DataForSEO API costs into specific features?

OpenSEO uses the mapDataforseoPathToCreditFeature utility in src/shared/billing-credit-features.ts to parse the response path from each DataForSEO call and map it to a canonical feature identifier. This allows the platform to attribute costs from endpoints like /v3/dataforseo_labs/google/related_keywords/live to the "keyword_research" feature for billing and analytics purposes.

What determines how many credits a DataForSEO request consumes?

The credit cost derives from the raw USD price returned by DataForSEO, multiplied by the AUTUMN_SEO_DATA_CREDITS_PER_USD conversion rate defined in src/shared/billing.ts. For hosted deployments, the system applies SEO_DATA_COST_MARKUP via the applyBillingMarkupUsd function before converting to credits, meaning the final deduction reflects both the base API cost and platform fees.

Where can I verify that OpenSEO recorded my DataForSEO usage correctly?

The getBillingUsageEvents function in src/serverFunctions/billing.ts queries the Autumn billing service for all usage_credits and topup_credits events, returning a timestamped ledger of every deduction. Additionally, the test suite in src/server/lib/dataforseo/client.test.ts contains test cases that verify credit deductions are recorded accurately for various DataForSEO API responses.

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