Hep.gg Documentation

AI Usage JavaScript SDK

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

Read via MCP

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 the windows five_hour, seven_day (weekly, all models), and weekly_scoped (the per-model weekly cap, for example Fable, labelled by whichever model Anthropic currently scopes it to), 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.