Claude Usage API Nutzungsdaten direkt aus der CLI-Proxy-API

v2.0 cug.np200.de API-Key optional

Liefert den aktuellen Claude-Verbrauch (5-Stunden-Session, Wochenlimits, Credits) als JSON. Die Daten kommen über die CLI-Proxy-API, die mit dem dort hinterlegten Claude-OAuth-Credential Anthropics /api/oauth/usage abfragt — also exakt die Zahlen, die auch /status in Claude Code anzeigt.

ℹ️ Kein Browser, kein Scraping. Antwortzeit typischerweise unter 500 ms; Antworten werden serverseitig gecacht (Standard 60 s), weil Anthropic den Usage-Endpunkt aggressiv rate-limited.

Authentifizierung

Falls ein API-Key gesetzt ist, muss er bei jedem Request übermittelt werden:

Query-Parameter

?key=DEIN_KEY

HTTP-Header

X-Api-Key: DEIN_KEY

Bearer Token

Authorization: Bearer DEIN_KEY

⚠️ Geschützt sind /api/info, /api/info/all und /api/accounts. /health und /api/doku sind immer öffentlich erreichbar.

GET /api/info

GET https://cug.np200.de/api/info

Alle Nutzungsdaten eines Kontos als strukturiertes JSON. Mit ?refresh=1 wird der Cache übersprungen und frisch abgefragt.

Mehrere Konten: ?account=KONTO_ID wählt ein bestimmtes Konto. Ohne Angabe antwortet das erste Konto aus der accounts-Liste in config.json. Die verfügbaren IDs liefert /api/accounts.

Request

CURLcurl -H "X-Api-Key: mein-key" \
     https://cug.np200.de/api/info?account=account2

Response `200 OK`

JSON{
  "plan": "Max (20x)",
  "account": {
    "name": "NoPro200",
    "email": "…@gmail.com",
    "organization_type": "claude_max",
    "rate_limit_tier": "default_claude_max_20x",
    "subscription_status": "active"
  },
  "current_session": {
    "percent_used": 29,
    "resets_at": "2026-08-23T23:10:00+02:00",
    "resets_in_seconds": 4812,
    "reset_info": "Zurücksetzung in 1 Std. 20 Min.",
    "has_usage": true
  },
  "weekly": {
    "all_models":  { "percent_used": 24, "reset_info": "Sa., 14:00", … },
    "sonnet_only": { "percent_used":  0, "reset_info": null, … },
    "opus_only":   { … },
    "cowork":      { … },
    "scoped":      [{ "model": "Fable", "percent_used": 0 }]
  },
  "credits": {
    "percent_consumed":      0,
    "spent":                 "0,00 €",
    "spending_limit":        "0,00 €",
    "balance":               null,
    "currency":              "EUR",
    "auto_recharge_enabled": null,
    "extra_usage_enabled":   false,
    "spend_limit_reached":   false,
    "severity":              "normal"
  },
  "limits": [{ "kind": "session", "percent": 29, "severity": "normal", … }],
  "last_updated": "2026-08-23T21:52:07+02:00",
  "source":       "cliproxyapi"
}

GET /api/accounts

GET https://cug.np200.de/api/accounts

Liste der konfigurierten Konten in Anzeigereihenfolge — genau die Reiter des Dashboards. available: false heißt: für dieses Konto gibt es in der CLI-Proxy-API kein passendes Claude-Credential.

Response `200 OK`

JSON{
  "accounts": [
    { "id": "account1", "label": "Account 1", "email": "...", "available": true }
  ]
}

GET /api/info/all

GET https://cug.np200.de/api/info/all

Alle Konten in einem Request: {"accounts": [ … ]} mit je einem /api/info-Objekt in Config-Reihenfolge. Das Dashboard nutzt diesen Endpunkt, damit der Reiterwechsel ohne neue Anfrage auskommt. Scheitert ein einzelnes Konto, steht in dessen Eintrag error statt der Nutzungsdaten — die übrigen Konten kommen trotzdem durch.

GET /health

GET https://cug.np200.de/health

Liveness-Check ohne Auth. Antwortet mit {"status":"ok"}.

GET /

GET https://cug.np200.de/

Dashboard mit dem aktuellen Stand — Meter für Sitzung, Wochenlimits und Ausgabenlimit, dazu eine Tabellenansicht. Aktualisiert sich alle 60 s selbst. Ist ein API-Key konfiguriert, muss die Seite als /?key=DEIN_KEY aufgerufen werden — sie reicht den Key an /api/info weiter.

GET /api/doku

GET https://cug.np200.de/api/doku

Diese Seite. Das Dashboard liegt unter /.

Response-Schema

Wurzel

Feld	Typ	Beschreibung
`account_id`	string	ID des Kontos, passend zu `?account=`
`account_label`	string	Anzeigename aus `config.json`, z. B. `Account 1`
`plan`	string	Plan inkl. Multiplikator, z. B. `Max (20x)`
`account`	object	Konto- und Organisationsdaten
`current_session`	object	5-Stunden-Fenster
`weekly`	object	Wochenlimits nach Modell
`credits`	object	Nutzungsguthaben und Ausgabenlimit
`limits`	array	Rohe Limit-Liste von Anthropic (durchgereicht)
`last_updated`	string	ISO-Zeitstempel des Abrufs (lokale Zeitzone)
`stale`	boolean	Nur vorhanden, wenn ein veralteter Cache geliefert wurde (z. B. bei 429)

Limit-Fenster (`current_session`, `weekly.*`)

Feld	Typ	Beschreibung
`percent_used`	integer	Verbrauch in % (0–100)
`resets_at`	string / null	ISO-Zeitstempel der Zurücksetzung
`resets_in_seconds`	integer / null	Restzeit in Sekunden — ideal für HA-Templates
`reset_info`	string / null	Menschenlesbar; Session als Countdown, Wochenlimits als `Sa., 14:00`
`has_usage`	boolean	`true` wenn in diesem Fenster bereits Verbrauch angefallen ist

credits

Feld	Typ	Beschreibung
`percent_consumed`	integer	Anteil des Ausgabenlimits in %
`spent`	string / null	Bereits ausgegeben, z. B. `0,00 €`
`spending_limit`	string / null	Monatliches Ausgabenlimit
`balance`	string / null	Aktuelles Guthaben
`extra_usage_enabled`	boolean / null	`true` wenn Nutzungsguthaben aktiv
`severity`	string	`normal` / `warning` / …

Fehler-Codes

Code	Bedeutung	Ursache
200	OK	Daten erfolgreich abgerufen
401	Unauthorized	Kein oder ungültiger API-Key
502	Bad Gateway	CLI-Proxy-API nicht erreichbar, Management-Key falsch, kein Claude-Credential hinterlegt, oder Anthropic antwortet mit Fehler. Details im `error`-Feld.

JSON — Fehlerantwort{
  "error": "CLI-Proxy-API unter http://192.168.3.62:8317 nicht erreichbar: …"
}

Beispiele

Python

Pythonimport requests

r = requests.get(
    "https://cug.np200.de/api/info",
    headers={"X-Api-Key": "mein-key"},
    timeout=30
)
d = r.json()
print(f"{d['plan']}: Session {d['current_session']['percent_used']}%, "
      f"Woche {d['weekly']['all_models']['percent_used']}%")

Home Assistant REST-Sensor

YAMLrest:
  - resource: https://cug.np200.de/api/info?key=mein-key
    scan_interval: 120
    sensor:
      - name: Claude Session
        value_template: "{{ value_json.current_session.percent_used }}"
        unit_of_measurement: "%"
      - name: Claude Woche
        value_template: "{{ value_json.weekly.all_models.percent_used }}"
        unit_of_measurement: "%"
      - name: Claude Session Reset
        device_class: timestamp
        value_template: "{{ value_json.current_session.resets_at }}"

JavaScript / fetch

JSconst d = await fetch("https://cug.np200.de/api/info", {
  headers: { "X-Api-Key": "mein-key" }
}).then(r => r.json());

console.log(d.current_session.reset_info); // "Zurücksetzung in 1 Std. 20 Min."

Claude Usage API Nutzungsdaten direkt aus der CLI-Proxy-API

Authentifizierung

GET /api/info

Request

Response 200 OK

GET /api/accounts

Response 200 OK

GET /api/info/all

GET /health

GET /

GET /api/doku

Response-Schema

Wurzel

Limit-Fenster (current_session, weekly.*)

credits

Fehler-Codes

Beispiele

Python

Home Assistant REST-Sensor

JavaScript / fetch

Response `200 OK`

Response `200 OK`

Limit-Fenster (`current_session`, `weekly.*`)