# How OpenSEO Tracks API Costs Using DataForSEO’s Billing Classification

> Learn how OpenSEO tracks API costs with DataForSEO's billing classification. Discover how requests are mapped to features and credits are deducted from your SEO data balance.

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

---

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

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

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

```typescript
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`](https://github.com/every-app/open-seo/blob/main/src/server/mcp/tools/whoami.ts)**:

```typescript
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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/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`](https://github.com/every-app/open-seo/blob/main/src/server/lib/dataforseo/client.test.ts) contains test cases that verify credit deductions are recorded accurately for various DataForSEO API responses.