Billing & Credits

Workspace usage is metered and billed through the credits system. This page explains how usage converts to credits.

How billing works

1. While a workspace is running, the platform collects usage metrics (CPU time, memory, disk I/O, network)
2. Metrics are collected and converted to pricing units
3. Credits are debited from your account balance

Credits vs. quotas — two layers

Oblien separates money from limits:

• Credit balance + ledger — your spendable balance, backed by an immutable transaction ledger. Usage deducts; top-ups and grants add. This is the source of truth for "how many credits were used."
• Namespace quotas (optional) — per-(namespace, service) ceilings with overdraft + threshold actions, for capping what a tenant can spend. A quota is a limit, not a balance, and Oblien does not run a billing period against it — you own the renewal cycle (see Namespace quotas).

Use the balance alone, or layer namespace quotas on top for hard per-tenant caps.

Pricing units

Credit rates

Credit rates vary by plan and can be checked from the Dashboard → Credits → Pricing page.

What costs credits

Managing costs

Use temporary mode

Auto-expire workspaces to avoid forgetting to stop them:

await ws.create({
  config: { ttl: '1h', ttl_action: 'stop' },
});

Right-size resources

Don't over-provision. Start small and scale up:

// Start with minimum resources
await ws.create({
  config: { cpus: 1, memory_mb: 256 },
});

// Scale up only when needed
await ws.resources.update(id, { cpus: 4, memory_mb: 4096, apply: true });

Pause when idle

Paused workspaces consume far less than running ones:

await ws.pause(id); // Freeze - minimal cost
await ws.resume(id); // Resume when needed

Set namespace quotas

Cap per-tenant spending with namespace quotas — from the SDK or the Dashboard → Credits → Quotas.

Monitor usage

Track credit consumption in real-time:

// Credits chart for a workspace
const chart = await ws.usage.creditsChart(id);
console.log(`Total credits burned: ${chart.total}`);

Namespace quotas

Optional per-(namespace, service) spending ceilings. Set them from the SDK (client.namespaces.setQuota) or the Dashboard. Key semantics:

• setQuota replaces the ceiling and preserves consumption. Calling setQuota({ quotaLimit }) mid-cycle changes the limit but does not reset quota_used. So a top-up is setQuota({ quotaLimit: currentLimit + topup }), and a tier upgrade is setQuota({ quotaLimit: newAllowance }) — consumption carries over against the new ceiling (Free 200/500 → Pro → 200/5000, never stacked). It also re-arms the threshold notifications.
• Usage auto-increments quota_used by the same credits charged to the balance.
• resetQuota zeroes quota_used and re-arms thresholds — this is the renewal. You call it on your own cycle; Oblien does not auto-reset (no calendar/anchor period and no reset webhook — the period fields are deprecated).
• Overdraft + thresholds — overdraft is a grace zone beyond the limit; onOverdraftAction (block | stop_workspaces) fires when it's exceeded; notificationThresholds (default [80, 95]) fire the namespace.quota.threshold webhook.
• Refunds decrement quota_used (floored at 0).

Full reference: Namespaces API → Quotas.

Using Oblien as your billing source of truth

Building external billing on top of Oblien:

• Raw usage units — client.namespaces.usageUnits(ns, { from, to, groupBy }) returns time-bucketed raw metered units (cpu_time_minutes, memory_gb_minutes, disk_io_gb, network_gb, plus derived vcpu_hours / gb_hours) so you can apply your own rates. Deterministic for a range → poll and idempotency-key on (namespace, bucket). Or subscribe the credits.usage webhook for the same units pushed per billing cycle.
• credits is authoritative. The credits value (in usageUnits, the ledger, and the credits.usage webhook) all come from one pricing engine — the exact amount charged to your balance and quota. There's no separate conversion table to maintain. The ledger value is the source of truth to display.
• You own the period. Oblien meters continuously; run your own renewal cron (e.g. your Stripe anniversary) and call resetQuota + grant the new period's allowance. Oblien doesn't impose a calendar month.
• Retention — the transaction ledger is immutable and retained indefinitely, so 90-day (and longer) historical queries via usageUnits are safe. Usage read endpoints aren't rate-limited.

Plan allowances & credit packages

For current plan credit allowances, pricing, and available credit packages, see the Pricing page.