# How OpenSEO Calculates DataForSEO API Usage Costs: Technical Implementation Guide

> Learn how OpenSEO calculates DataForSEO API usage costs. Discover the 1.28x markup, credit conversion, and Stripe or credit pool charging methods.

- Repository: [Every App/open-seo](https://github.com/every-app/open-seo)
- Tags: technical-implementation-guide
- Published: 2026-06-26

---

**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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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:

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

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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/shared/billing.ts).
- **Real-time cost capture** occurs in [`src/server/lib/dataforseo/serp.ts`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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.