---
title: Hep.gg AI Usage JavaScript SDK (LLM)
description: Read AI Gateway usage/quota from Node/TypeScript via the hepgg package.
---

# Hep.gg AI Usage SDK (hepgg package)

Read-only Node/TypeScript client for the AI Gateway usage API. Subpath:
`hepgg/ai`. Part of the unified `hepgg` package. Node 20+. Covers usage/quota
only, not inference (use the OpenAI-compatible endpoint or Claude proxy for chat).

## Install

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

## Construct

  import { AIUsage } from "hepgg/ai";
  const ai = new AIUsage({ token, baseURL?, timeoutMs?, retries?, fetch? });

  token   string  required. Read-only usage token. Sent as Authorization: Bearer <token>.
  baseURL string  optional. Default https://ai.hep.gg.

## Methods

  ai.usage()       -> UsageResponse              GET /usage   (all pooled accounts)
  ai.usageFor(id)  -> AccountUsage               GET /usage/{id}

UsageResponse: { version, fetched_at, accounts: AccountUsage[] }
AccountUsage: { id, label, plan { rate_limit_tier, label }, status, error, fetched_at,
  windows { five_hour, seven_day, seven_day_sonnet, claude_design }, raw_usage }
Window (nullable): { utilization (0-100), resets_at, expected?, pace_delta?, pace? }
status: "ok" | "rate_limited" | "auth_error" | "error".

Behavior: always returns 200 (served from cache); inspect per-account status for
degraded fetches. Last good windows are kept while degraded.

## Errors

Transport failure or bad token throws HepError { status, code, service: "ai", message, body }.

## Part of the hepgg package

Also provides: hepgg/id, hepgg/sms, hepgg/email, hepgg/uploader, hepgg/paste,
hepgg/secrets, hepgg/login, hepgg/logger (logger docs:
https://docs.teamhydra.dev/docs/logger/getting-started).
Full AI reference: /llms/ai/usage-api, /llms/ai/openai-compatible, /llms/ai/claude-proxy.