Credits

The credits module lets you query your deployment's credit balance, track usage across services, view purchasable credit packs, and configure credit settings like overage behavior and AI provider priority.

Access the credits proxy via hiveforge.credits.

import { HiveForgeClient } from '@producthacker/hiveforge-sdk';
 
const hiveforge = new HiveForgeClient({
  deploymentId: process.env.HIVEFORGE_DEPLOYMENT_ID!,
  deploymentSecret: process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
});
await hiveforge.initialize();
 
const balance = await hiveforge.credits.getBalance();
console.log(`${balance.totalAvailable} credits available`);

Methods

`getBalance()`

Get the current credit balance for your deployment, including plan allocation and purchased credits.

const balance = await hiveforge.credits.getBalance();
 
console.log(`Period balance: ${balance.periodBalance}`);
console.log(`Purchased balance: ${balance.purchasedBalance}`);
console.log(`Total available: ${balance.totalAvailable}`);
console.log(`Monthly allocation: ${balance.monthlyAllocation}`);
console.log(`Period ends: ${balance.periodEnd}`);
console.log(`Overage mode: ${balance.overageMode}`);
console.log(`AI provider: ${balance.aiProviderPriority}`);

Returns (CreditBalance):

Field	Type	Description
`periodBalance`	`number`	Credits remaining from monthly plan allocation
`purchasedBalance`	`number`	Credits remaining from purchased packs
`totalAvailable`	`number`	Total credits available (period + purchased)
`monthlyAllocation`	`number`	Monthly credit allocation from the plan
`periodEnd`	`string`	ISO timestamp when current billing period ends
`overageMode`	`'block' \| 'allow' \| 'auto_purchase'`	How credit exhaustion is handled
`aiProviderPriority`	`'openai' \| 'anthropic'`	Preferred AI provider

Equivalent curl request

curl -X GET https://api.hiveforge.dev/api/v1/entitlements/credits \
  -H "Content-Type: application/json" \
  -H "X-Deployment-ID: d9f2a1b4-7c3e-4f8a-b5d6-1e2f3a4b5c6d" \
  -H "X-Deployment-Secret: sk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

`getUsage(startDate?, endDate?)`

Get credit usage for your deployment, broken down by service and action.

// Current period usage
const usage = await hiveforge.credits.getUsage();
console.log(`Total credits used: ${usage.totalCreditsUsed}`);
console.log('By service:', usage.byService);
console.log('By action:', usage.byAction);
 
// Custom date range
const startOfMonth = new Date('2026-03-01');
const endOfMonth = new Date('2026-03-31');
const monthlyUsage = await hiveforge.credits.getUsage(startOfMonth, endOfMonth);
console.log(`March usage: ${monthlyUsage.totalCreditsUsed} credits`);

Parameters:

Parameter	Type	Required	Description
`startDate`	`Date`	No	Start of the usage query period
`endDate`	`Date`	No	End of the usage query period

Returns (CreditUsage):

Field	Type	Description
`totalCreditsUsed`	`number`	Total credits consumed in the period
`byService`	`Record<string, number>`	Usage grouped by service (e.g., `{ ai: 450, email: 20 }`)
`byAction`	`Record<string, number>`	Usage grouped by action (e.g., `{ completion: 400, embedding: 50 }`)
`periodStart`	`string`	Optional ISO timestamp for period start
`periodEnd`	`string`	Optional ISO timestamp for period end

`getPacks()`

List available credit packs for purchase.

const packs = await hiveforge.credits.getPacks();
 
for (const pack of packs) {
  const price = (pack.priceCents / 100).toFixed(2);
  console.log(`${pack.name}: ${pack.credits} credits for $${price}`);
}

Returns: CreditPack[]

Field	Type	Description
`id`	`string`	Credit pack identifier
`name`	`string`	Display name
`credits`	`number`	Number of credits in the pack
`priceCents`	`number`	Price in cents (USD)

`getCosts()`

Get the credit cost for every available action across all services.

const costs = await hiveforge.credits.getCosts();
 
for (const cost of costs) {
  console.log(`${cost.service}/${cost.action}: ${cost.credits} credits`);
  if (cost.description) {
    console.log(`  ${cost.description}`);
  }
}

Returns: CreditCost[]

Field	Type	Description
`service`	`string`	Service name (e.g., `'ai'`, `'email'`, `'vectors'`)
`action`	`string`	Action name (e.g., `'completion'`, `'send'`, `'search'`)
`credits`	`number`	Credit cost per action
`description`	`string`	Optional human-readable description

`setAIProviderPriority(priority)`

Set the preferred AI provider for your deployment.

await hiveforge.credits.setAIProviderPriority('anthropic');

Parameters:

Parameter	Type	Required	Description
`priority`	`'openai' \| 'anthropic'`	Yes	Preferred AI provider

Returns: Promise<void>

`setOverageMode(mode)`

Configure how your deployment handles credit exhaustion.

// Block all service calls when credits run out
await hiveforge.credits.setOverageMode('block');
 
// Allow continued usage (will be billed at overage rate)
await hiveforge.credits.setOverageMode('allow');
 
// Automatically purchase the smallest credit pack
await hiveforge.credits.setOverageMode('auto_purchase');

Parameters:

Parameter	Type	Required	Description
`mode`	`'block' \| 'allow' \| 'auto_purchase'`	Yes	Overage handling mode

Returns: Promise<void>

⚠️

Setting overage mode to 'allow' or 'auto_purchase' may result in additional charges on your account.

Types

import type {
  CreditBalance,
  CreditUsage,
  CreditPack,
  CreditCost,
} from '@producthacker/hiveforge-sdk';

Full Example: Credits Dashboard

import { HiveForgeClient } from '@producthacker/hiveforge-sdk';
 
const hiveforge = new HiveForgeClient({
  deploymentId: process.env.HIVEFORGE_DEPLOYMENT_ID!,
  deploymentSecret: process.env.HIVEFORGE_DEPLOYMENT_SECRET!,
});
await hiveforge.initialize();
 
async function renderCreditsDashboard() {
  const [balance, usage, costs] = await Promise.all([
    hiveforge.credits.getBalance(),
    hiveforge.credits.getUsage(),
    hiveforge.credits.getCosts(),
  ]);
 
  const usagePercent = balance.monthlyAllocation > 0
    ? Math.round((usage.totalCreditsUsed / balance.monthlyAllocation) * 100)
    : 0;
 
  console.log(`Credits: ${balance.totalAvailable} available`);
  console.log(`Usage: ${usagePercent}% of monthly allocation`);
  console.log(`Period ends: ${balance.periodEnd}`);
 
  // Show per-service breakdown
  for (const [service, creditsUsed] of Object.entries(usage.byService)) {
    console.log(`  ${service}: ${creditsUsed} credits`);
  }
 
  // Show cost table
  console.log('\nCredit costs:');
  for (const cost of costs) {
    console.log(`  ${cost.service}/${cost.action}: ${cost.credits} credits`);
  }
}

Billing Email