How OpenSEO Calculates DataForSEO API Usage Costs: Technical Implementation Guide

OpenSEO meters every DataForSEO API call by applying a fixed 1.28x markup to raw USD costs, converting the result to internal credits at a rate of 1,000 credits per dollar, and finalizing charges through Stripe for hosted customers or credit pool deductions for self-hosted deployments.

Understanding exactly how OpenSEO DataForSEO API usage costs are calculated requires tracing the path from raw vendor pricing to final customer billing. In the every-app/open-seo repository, the platform implements a deterministic pipeline that captures live API responses, applies standardized markups, and normalizes everything into a unified credit system. This article breaks down the specific functions and file paths that handle cost estimation, real-time expenditure tracking, and credit conversion.

Defining Base Rates and Per-SERP Cost Estimation

OpenSEO stores the underlying DataForSEO pricing as constants to enable deterministic cost prediction before any API call is made.

Storing Raw DataForSEO Rates

The base-page and extra-page costs for DataForSEO's two access methods—instant "live" endpoints and cheaper "queued" task queues—are defined in src/shared/rank-tracking.ts at lines 12-22. These constants represent the raw vendor pricing that OpenSEO pays before any platform markup is applied.

Computing Costs with costPerSerpAtDepth

The function costPerSerpAtDepth(depth, method) calculates the exact cost for a single SERP request by multiplying the number of pages (calculated as depth / 10) by the appropriate per-page price for either the live or queued method. This implementation appears at lines 46-52 in src/shared/rank-tracking.ts, providing accurate per-request pricing based on how deep the rank check needs to scan into search results.

Scaling to Batch Jobs with Markup

When calculating costs for bulk operations, estimateRankCheckCredits (lines 68-71 in src/shared/rank-tracking.ts) performs three critical steps:

1. Multiplies the per-SERP price by the total number of checks (keywordCount × devicesCount)
2. Applies the platform markup using the constant SEO_DATA_COST_MARKUP = 1.28 (representing a 28% markup)
3. Rounds the result using roundUsdForBilling to ensure billing precision

This function returns both the final USD amount and the equivalent credit cost, making it the central estimator for rank-check batch pricing.

Capturing Live API Costs and Billing Envelopes

While estimates predict costs, OpenSEO also captures actual expenditures from DataForSEO API responses to ensure billing accuracy.

Summing Raw Costs from SERP Responses

For queued tasks, the DataForSEO API returns a cost field per entry. The function googleOrganicTaskPost in src/server/lib/dataforseo/serp.ts (lines 48-67) sums these individual cost values into a consolidated costUsd total. This raw sum represents the exact amount DataForSEO charges OpenSEO before platform markup is applied.

Wrapping Costs in Billing Envelopes

Every DataForSEO response is wrapped by buildTaskBilling in src/server/lib/dataforseo/envelope.ts (lines 72-78). This function constructs a billing envelope containing the exact API request path and the precise costUsd charged by DataForSEO. This envelope attaches to every response, creating an immutable record of the raw expenditure for audit trails and customer transparency.

Applying Markup and Credit Conversion

Once raw costs are captured, OpenSEO converts them into the platform's internal currency system.

Implementing the Platform Markup

The function applyBillingMarkupUsd(rawUsd) in src/shared/billing.ts (lines 26-36) handles the markup calculation. Hosted customers see prices processed through this function, which multiplies the raw DataForSEO cost by 1.28 to cover platform operational expenses. Self-hosted deployments bypass this markup and pay DataForSEO directly at raw rates.

Converting USD to Internal Credits

OpenSEO operates on a credit system where AUTUMN_SEO_DATA_CREDITS_PER_USD = 1000. The helper autumnSeoDataCreditsToUsd converts credit balances back to USD for display purposes. When charging for actual usage, the platform calculates costCredits = Math.ceil(costUsd * AUTUMN_SEO_DATA_CREDITS_PER_USD) to determine the exact credit deduction from a customer's balance.

Billing Mode Differences

• Hosted Mode: Customers see the marked-up USD price (e.g., $0.0018 for a single SERP request) and are billed via Stripe. OpenSEO pays DataForSEO the raw rate and keeps the difference.
• Self-Hosted Mode: Customers pay DataForSEO directly at raw rates. OpenSEO displays the raw cost and deducts the equivalent credits from the internal usage pool without applying markup.

Practical Code Examples

Estimating Rank Check Batch Costs

Use estimateRankCheckCredits to calculate costs before submitting large batches:

import { estimateRankCheckCredits } from "@/shared/rank-tracking";

// 150 keywords, checking both desktop & mobile, depth = 30 (3 pages), queued method
const { costUsd, costCredits } = estimateRankCheckCredits(
  150,
  "both",          // devices
  30,              // depth (10 results per page)
  "queued",        // live vs queued
);

console.log(`≈ $${costUsd} (≈ ${costCredits} credits)`);
// Example output: ≈ $0.45 (≈ 450 credits)

Inspecting Billing Data from API Responses

Access the billing envelope to verify actual charges from any SERP request:

import { fetchSerp } from "@/server/lib/dataforseo/serp";

const result = await fetchSerp({
  tasks: [{ keyword: "open seo", device: "desktop", keywordId: "k1" }],
  locationCode: 2840,
  languageCode: "en",
  depth: 10,
});

console.log(result.billing);
// { path: ["v3","serp","google","organic","task_post"], costUsd: 0.0018 }

Converting Credit Balances to USD

Convert internal credits back to dollar amounts for reporting:

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

const credits = 2500;
const usd = autumnSeoDataCreditsToUsd(credits);
console.log(`$${usd}`); // $2.5

Summary

• Raw cost constants for DataForSEO live and queued methods are stored in src/shared/rank-tracking.ts and drive all price estimations.
• Per-SERP pricing scales linearly with search depth and applies a 1.28x platform markup via applyBillingMarkupUsd in src/shared/billing.ts.
• Real-time cost capture occurs in src/server/lib/dataforseo/serp.ts, where googleOrganicTaskPost sums actual DataForSEO charges into costUsd.
• Billing envelopes created by buildTaskBilling in src/server/lib/dataforseo/envelope.ts attach cost metadata to every API response.
• Credit conversion uses a fixed rate of 1,000 credits per USD, with hosted customers paying marked-up prices and self-hosted users paying raw rates.

Frequently Asked Questions

How does OpenSEO handle pricing differences between live and queued DataForSEO methods?

OpenSEO maintains separate rate constants for each method in src/shared/rank-tracking.ts. The "live" method uses DataForSEO's instant endpoints at a higher per-page rate, while the "queued" method uses the task-queue system at a discounted rate. The costPerSerpAtDepth function automatically selects the correct rate constant based on the method parameter passed to it.

What is the exact formula for converting DataForSEO costs to OpenSEO credits?

The conversion follows the formula costCredits = Math.ceil(costUsd * 1000), where costUsd is the final marked-up dollar amount (not the raw DataForSEO cost for hosted customers). The estimateRankCheckCredits function in src/shared/rank-tracking.ts returns both values, applying the 1.28x markup and rounding before credit calculation.

Where can developers find the raw cost DataForSEO charged for a specific API call?

Every response from OpenSEO's DataForSEO wrapper includes a billing property containing the exact costUsd charged by DataForSEO and the API path accessed. This envelope is generated by buildTaskBilling in src/server/lib/dataforseo/envelope.ts and attached to the response object, allowing real-time cost verification without parsing vendor invoices.

How does the platform markup differ between hosted and self-hosted deployments?

Hosted deployments process all DataForSEO costs through applyBillingMarkupUsd in src/shared/billing.ts, which applies the 28% markup (SEO_DATA_COST_MARKUP = 1.28) to raw vendor costs before charging customers via Stripe. Self-hosted deployments do not apply this markup; they display the raw costUsd from DataForSEO and deduct credits at the flat conversion rate of 1,000 credits per dollar, as the customer pays DataForSEO directly.

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