Hep.gg Documentation

AI Usage JavaScript SDK

Read AI Gateway usage and quota windows from Node and TypeScript with the hepgg package.

View as LLM-ready text

AI Usage SDK

The hepgg package includes a small, read-only client for the AI Gateway usage API on the hepgg/ai subpath. It reports per-account utilisation windows so you can build dashboards or alerts.

Install

flag
npm install hepgg --registry https://npm.hep.gg

Read Usage

import { AIUsage } from "hepgg/ai";
 
const ai = new AIUsage({ token: process.env.AI_USAGE_TOKEN });
 
const { accounts } = await ai.usage();
for (const a of accounts) {
  console.log(a.label, a.windows.five_hour?.utilization ?? 0, "%");
}
 
const one = await ai.usageFor("acct-1"); // usage for a single account by id

Each account reports four windows (five_hour, seven_day, seven_day_sonnet, claude_design), each with utilization (0 to 100), resets_at, and on-pace fields.

Degraded Accounts, Not Errors

The endpoint always returns 200 and keeps serving the last good windows while an account is degraded. Inspect account.status (ok, rate_limited, auth_error, error) instead of relying on a thrown error.

const { accounts } = await ai.usage();
const unhealthy = accounts.filter((a) => a.status !== "ok");

The constructor also takes baseURL, timeoutMs, retries, and fetch. A transport failure or a bad token still throws a typed HepError.

Full Reference

Usage API.