Credits

Read your organization's current credit balance and account level with its usage against that level's limits. This is the read-only entry point for a billing-status flow: call it before a run to check headroom, or render it in your own dashboard.

The endpoint never 404s: before any credit has been granted it returns a zero-state snapshot (balanceCents: 0) so you can call it as the first step without special-casing new accounts.

All cent amounts are US-dollar cents and may carry sub-cent precision (balanceCents can be fractional). Round at presentation time if you want whole-cent display.

Methods

| Method | Route | |---|---| | novo.credits.retrieve() | GET /v1/credits |

Credit purchases are made from the console billing screen and are not part of the SDK surface.

Type signature

type CreditBalance = {
  /** Current spendable balance, in cents. `0` before any grant has landed. */
  balanceCents: number;
  accountLimits: {
    level: {
      id: 'trial' | 'level_1' | 'level_2' | 'level_3' | 'level_4';
      label: string;
      /** Cumulative paid credits needed to reach this level, in cents (null for the trial gate). */
      unlockPaidCents: number | null;
      /** Monthly spend cap for this level, in cents (null when the balance is the only limiter). */
      monthlyCapCents: number | null;
      runStartsPerMinute: number;
      activeRuns: number;
    };
    /** Cumulative paid credits applied to the account, in cents. */
    paidCreditsCents: number;
    /** Spend in the current calendar month, in cents. */
    monthSpendCents: number;
    /** Run starts in the trailing minute. */
    runStartsLastMinute: number;
    /** Currently active runs. */
    activeRuns: number;
  };
};

type CreditsNamespace = {
  retrieve(): Promise<CreditBalance>;
};

Example

const credits = await novo.credits.retrieve();

console.log(`balance: $${(credits.balanceCents / 100).toFixed(2)}`);

if (credits.balanceCents <= 0) {
  throw new Error(
    'Out of credit. Ask an organization admin to purchase credits in the Novo billing console.',
  );
}

// Account level controls concurrency and run-rate limits:
const { level, activeRuns } = credits.accountLimits;
console.log(`${level.label}: ${activeRuns}/${level.activeRuns} active runs`);

accountLimits reflects your current account level and live usage against it: runStartsPerMinute and activeRuns on level are the ceilings, and runStartsLastMinute / activeRuns are your current draw. Your level rises as paidCreditsCents grows. To reconcile exact spend rather than check headroom, use the Usage API.