API Reference

Credits & Billing

Complete billing and quota management system for your platform.

Oblien provides a powerful credits system that lets you manage usage, set quotas, and track consumption across multiple levels. Perfect for SaaS products, marketplaces, and multi-tenant applications.

Overview

Oblien provides a two-level quota system for managing credits across all services (especially AI tokens):

Level 1: Namespace - Set quotas per workspace/project/app for all services
Level 2: End User - Set quotas per individual user within a namespace (optional)

How It Works

Client Credits → Namespace Quotas → End User Quotas (optional)

Example:

  • Purchase 10,000 credits
  • Set namespace "production" quota: 5,000 credits/month for ai_chat
  • Set end user "user_123" quota: 500 credits/month within "production"
  • User consumes: their quota → namespace quota → your balance

Key Points:

  • Namespaces manage quotas at the workspace/app level
  • End users are individual users under that namespace/app
  • Both levels work across all services (AI tokens, sandbox, deployments, etc.)
  • End user quotas are optional - if not set, users consume from namespace quota

Features

  • Credit Management - Purchase, track balance, transaction history
  • Namespace Quotas - Set limits per workspace/app/service (monthly, daily, unlimited)
  • End User Quotas - Optional per-user limits within namespaces
  • Usage Tracking - Real-time consumption, quota remaining, service breakdown
  • Analytics - Usage by namespace/service/user, trends, transaction history

API Usage

Get Balance

Get your current credit balance.

const balance = await credits.getBalance();
console.log(balance); // 15000.50
const response = await fetch('https://api.oblien.com/credits/balance', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});
const { balance } = await response.json();
curl -X GET https://api.oblien.com/credits/balance \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Get All Namespace Quotas

List all namespace quotas with pagination and filtering. Use this to see quotas across all your workspaces/apps.

const result = await credits.getNamespaceQuotas({
  limit: 100,
  search: 'production',
  status: 'active'
});
const response = await fetch('https://api.oblien.com/credits/namespaces?limit=100&search=production', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});
const result = await response.json();
curl -X GET "https://api.oblien.com/credits/namespaces?limit=100" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Get Namespace Details

Get detailed information for a specific namespace including quotas, usage statistics, and recent transactions.

import { OblienClient } from 'oblien';
import { OblienCredits } from 'oblien/credits';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

const credits = new OblienCredits(client);

// Get detailed namespace information including quotas
const details = await credits.getNamespaceDetails('production', {
  days: 7
});

console.log(details.quotas);        // Quota info per service
console.log(details.usage);         // Usage statistics
console.log(details.transactions); // Recent transactions
const response = await fetch('https://api.oblien.com/credits/namespaces/production?days=7', {
  method: 'GET',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const details = await response.json();
console.log(details);
curl -X GET "https://api.oblien.com/credits/namespaces/production?days=7" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "namespace": "production",
  "quotas": [
    {
      "service": "ai_chat",
      "limit": 1000,
      "used": 250,
      "remaining": 750,
      "period": "monthly",
      "enabled": true
    }
  ],
  "usage": {
    "total_spent": 250,
    "by_service": {
      "ai_chat": 250
    }
  },
  "transactions": [...]
}

Set Namespace Quota

Set or update quota limits for a namespace and service. Use this to control spending at the workspace/app level.

const result = await credits.setQuota({
  namespace: 'production',
  service: 'ai_chat',
  quotaLimit: 1000,
  period: 'monthly'
});

console.log(result);
const response = await fetch('https://api.oblien.com/credits/namespace-quota', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    namespace: 'production',
    service: 'ai_chat',
    quotaLimit: 1000,
    period: 'monthly'
  })
});

const result = await response.json();
console.log(result);
curl -X POST https://api.oblien.com/credits/namespace-quota \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production",
    "service": "ai_chat",
    "quotaLimit": 1000,
    "period": "monthly"
  }'

Response:

{
  "success": true,
  "namespace": "production",
  "service": "ai_chat",
  "quotaLimit": 1000,
  "period": "monthly"
}

Get End User Quota

Check quota status for a specific end user within a namespace. Returns limit, used, and remaining credits.

const quota = await credits.getEndUserQuota(
  'production',
  'user_123',
  'ai_chat'
);

console.log(quota.quota.limit);
console.log(quota.quota.used);
console.log(quota.quota.remaining);
const response = await fetch('https://api.oblien.com/credits/end-users/quota?namespace=production&endUserId=user_123&service=ai_chat', {
  method: 'GET',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const quota = await response.json();
console.log(quota);
curl -X GET "https://api.oblien.com/credits/end-users/quota?namespace=production&endUserId=user_123&service=ai_chat" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "quota": {
    "limit": 100,
    "used": 25,
    "remaining": 75,
    "period": "monthly",
    "enabled": true
  }
}

Set End User Quota

Set or update quota limits for an individual user within a namespace. Use this for per-user spending controls.

const result = await credits.setEndUserQuota({
  namespace: 'production',
  endUserId: 'user_123',
  service: 'ai_chat',
  quotaLimit: 100,
  period: 'monthly'
});

console.log(result);
const response = await fetch('https://api.oblien.com/credits/end-users/quota', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    namespace: 'production',
    endUserId: 'user_123',
    service: 'ai_chat',
    quotaLimit: 100,
    period: 'monthly'
  })
});

const result = await response.json();
console.log(result);
curl -X POST https://api.oblien.com/credits/end-users/quota \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "production",
    "endUserId": "user_123",
    "service": "ai_chat",
    "quotaLimit": 100,
    "period": "monthly"
  }'

Response:

{
  "success": true,
  "namespace": "production",
  "endUserId": "user_123",
  "service": "ai_chat",
  "quotaLimit": 100,
  "period": "monthly"
}

Reset Quota

Reset usage counter for a namespace quota (e.g., for monthly resets). This resets the used amount to 0.

await credits.resetQuota('production', 'ai_chat');
await fetch('https://api.oblien.com/credits/reset-quota', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ namespace: 'production', service: 'ai_chat' })
});
curl -X POST https://api.oblien.com/credits/reset-quota \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "production", "service": "ai_chat"}'

Reset End User Quota

Reset usage counter for an end user quota. Use this when resetting per-user limits at period boundaries.

await credits.resetEndUserQuota('production', 'user_123', 'ai_chat');
await fetch('https://api.oblien.com/credits/end-users/reset', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    namespace: 'production',
    endUserId: 'user_123',
    service: 'ai_chat'
  })
});
curl -X POST https://api.oblien.com/credits/end-users/reset \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"namespace": "production", "endUserId": "user_123", "service": "ai_chat"}'

Get Usage History

Get transaction history with filtering by namespace, end user, service, date range, and type. Supports pagination.

const history = await credits.getHistory({
  namespace: 'production',
  endUserId: 'user_123',
  service: 'ai_chat',
  limit: 50,
  offset: 0
});

console.log(history.data);
console.log(history.pagination);
const response = await fetch('https://api.oblien.com/credits/history?namespace=production&endUserId=user_123&service=ai_chat&limit=50&offset=0', {
  method: 'GET',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const history = await response.json();
console.log(history);
curl -X GET "https://api.oblien.com/credits/history?namespace=production&endUserId=user_123&service=ai_chat&limit=50&offset=0" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "data": [
    {
      "id": "txn_123",
      "namespace": "production",
      "endUserId": "user_123",
      "service": "ai_chat",
      "amount": 10.5,
      "description": "Chat message",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 150
}

Get Usage Summary

Get aggregated usage summary by namespace and service. Shows total spending over a specified time period.

const summary = await credits.getSummary({
  namespace: 'production',
  days: 30
});
const response = await fetch('https://api.oblien.com/credits/summary?namespace=production&days=30', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});
const summary = await response.json();
curl -X GET "https://api.oblien.com/credits/summary?namespace=production&days=30" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Get Usage Stats

Get daily usage statistics for charts and analytics. Returns breakdown by day over the specified period.

const stats = await credits.getUsageStats({ days: 7 });
const response = await fetch('https://api.oblien.com/credits/usage-stats?days=7', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});
const stats = await response.json();
curl -X GET "https://api.oblien.com/credits/usage-stats?days=7" \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Pricing

Credits are consumed when using Oblien SDK methods and API endpoints. Each service has its own pricing structure (tokens, minutes, requests, etc.).

Get Current Pricing

Retrieve current pricing information for all services. Use this to get real-time cost per unit for each service.

const pricing = await credits.getPricingInfo();

// Get pricing for a specific service
const aiChatPricing = pricing.services.find(s => s.service === 'ai_chat');
console.log(`AI Chat: ${aiChatPricing.cost_per_unit} credits per ${aiChatPricing.unit_name}`);
const response = await fetch('https://api.oblien.com/credits/pricing-info', {
  method: 'GET',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const pricing = await response.json();
console.log(pricing.services);
curl -X GET https://api.oblien.com/credits/pricing-info \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Response:

{
  "success": true,
  "services": [
    {
      "service": "ai_chat",
      "cost_per_unit": 0.001,
      "unit_name": "token",
      "description": "AI chat per token"
    },
    {
      "service": "ai_image",
      "cost_per_unit": 0.05,
      "unit_name": "image",
      "description": "AI image generation per image"
    },
    {
      "service": "sandbox",
      "cost_per_unit": 0.10,
      "unit_name": "minute",
      "description": "Sandbox execution per minute"
    },
    {
      "service": "deployment",
      "cost_per_unit": 1.00,
      "unit_name": "deployment",
      "description": "Code deployment per deployment"
    },
    {
      "service": "storage",
      "cost_per_unit": 0.001,
      "unit_name": "mb",
      "description": "File storage per MB"
    },
    {
      "service": "cdn",
      "cost_per_unit": 0.001,
      "unit_name": "request",
      "description": "CDN request per request"
    }
  ]
}

Calculate Cost

Calculate credits from money amount, package ID, or convert credits to money. Use this before purchases to preview costs.

// Calculate credits from package
const pkg = await credits.calculateCost({
  packageId: 'pro'
});

// Calculate credits from amount
const fromMoney = await credits.calculateCost({
  amount: 100  // $100
});
console.log('Credits:', fromMoney.credits);

// Calculate money from credits
const fromCredits = await credits.calculateCost({
  credits: 50000
});
console.log('Cost:', fromCredits.amount);
const response = await fetch('https://api.oblien.com/credits/calculate-cost', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    packageId: 'pro'
    // OR amount: 100
    // OR credits: 50000
  })
});

const result = await response.json();
console.log(result);
curl -X POST https://api.oblien.com/credits/calculate-cost \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "packageId": "pro"
  }'

Response:

{
  "success": true,
  "packageId": "pro",
  "amount": 80.00,
  "credits": 10000,
  "rate": 125.00
}

Services: AI Chat (per token), AI Image (per image), Sandbox (per minute), Deployments (per deployment), Storage (per MB), CDN (per request)

Note: Pricing is dynamic. Always query the API for current rates. View full pricing →

Get Packages

Get available credit packages with pricing. Use this to display purchase options to users.

const packages = await credits.getPackages();
const response = await fetch('https://api.oblien.com/credits/packages', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});
const { packages } = await response.json();
curl -X GET https://api.oblien.com/credits/packages \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

Purchase Credits

Create a Stripe checkout session to purchase credits. Returns a checkout URL to redirect users for payment.

// By package
const checkout = await credits.createCheckout({ packageId: 'pro' });

// Custom amount
const checkout = await credits.createCheckout({ amount: 100 });
console.log(checkout.checkoutUrl); // Redirect user here
const response = await fetch('https://api.oblien.com/credits/purchase', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ packageId: 'pro' })
});
const { checkoutUrl } = await response.json();
curl -X POST https://api.oblien.com/credits/purchase \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"packageId": "pro"}'

Best Practices

Setting Quotas:

  • Namespace: Set based on customer tier, use monthly periods, enable alerts at 80%
  • End User: Set defaults for new users, adjust by tier, monitor top consumers

Monitoring:

  • Review daily reports, track trends, set quota warnings, monitor balance thresholds

Optimization:

  • Match quotas to usage, review regularly, clean up unused quotas, optimize resource allocation

Use Cases

SaaS Product: Namespace per customer → Set quota by plan → Optional per-user limits for free tier

Marketplace: Namespace = workspace, End user = marketplace user → Set per-user spending limits

Developer Tools: Namespace = API key workspace, End user = API consumer → Quotas per API key

Documentation

Getting Help

Questions about credits?

Ready to set up credits? Configure your first quota →

Agents

Create and manage AI agents with custom prompts, settings, and tools

Framework Integration

Complete examples for Express, Next.js, and other frameworks

On this page

Credits & Billing
Overview
How It Works
Features
API Usage
Get Balance
Get All Namespace Quotas
Get Namespace Details
Set Namespace Quota
Get End User Quota
Set End User Quota
Reset Quota
Reset End User Quota
Get Usage History
Get Usage Summary
Get Usage Stats
Pricing
Get Current Pricing
Calculate Cost
Get Packages
Purchase Credits
Best Practices
Use Cases
Documentation
Getting Help