N/llm adds async getRemainingUsage.promise() for AI Unit balance checks

What changed

A new asynchronous method, llm.getRemainingUsage.promise(), has been added to the N/llm module in SuiteScript 2.1 (2026.1). It is the promise-based counterpart to the synchronous llm.getRemainingUsage().

• Returns: a Promise that resolves with the number of AI Units remaining on the account.
• Governance: None — calling this method does not consume governance units.
• Supported context: Server-side scripts only (Scheduled, Map/Reduce, Suitelet, User Event, RESTlet, etc.).
• Parameters and thrown errors: identical to llm.getRemainingFreeUsage().

Note the distinction between the two related methods:

• llm.getRemainingUsage() / .promise() — returns total remaining AI Units (paid entitlement).
• llm.getRemainingFreeUsage() / .promise() — returns remaining free-tier AI Units.

Syntax

Because this is a SuiteScript 2.1 promise API, use .then() (or await in an async entry point):

llm.getRemainingUsage.promise().then(function(remaining) {
  log.debug('AI Units left', remaining);
});

What to do

1. Prefer the async variant in long-running scripts. In Map/Reduce or Scheduled scripts where you check AI Unit balance before dispatching LLM calls, use llm.getRemainingUsage.promise() to avoid blocking the thread.
2. Guard LLM-heavy workflows. Call this method before expensive llm.generateText or llm.chat operations so you can bail out or queue work when units are low, rather than catching a usage-exceeded error mid-run.
3. Update your module imports. If you are already loading N/llm you do not need an additional dependency — the promise method hangs directly off the existing getRemainingUsage function.
4. Distinguish paid vs. free balance. If your logic previously used getRemainingFreeUsage, confirm whether you actually need the free-tier count or the total entitlement count. The two methods return different values.