Usage-API

GET /v1/usage gibt aggregierte Token- und Kostendaten für den API-Schlüssel im Header Authorization zurück. Gruppieren Sie die Daten nach Tag oder Stunde und teilen Sie sie optional nach Modell auf. Ein Zugriff auf die Daten eines anderen Schlüssels ist nicht möglich. Melden Sie sich dafür im Dashboard an.

Authentifizierung

Übergeben Sie Ihren Kunavo-API-Schlüssel als Bearer-Token – denselben Schlüssel, dessen Verbrauch Sie abfragen möchten. Der Endpunkt gibt nur den Verbrauch zurück, der diesem bestimmten Schlüssel in Rechnung gestellt wurde. Es gibt keinen Parameter, mit dem Sie die Daten eines anderen Schlüssels abrufen können.

Anfrage

Beispiele

Tagessummen der letzten 30 Tage, zusammengefasst über alle Modelle:

# Daily totals for the last 30 days
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-04-28" \
  --data-urlencode "end_date=2026-05-27"

Eine Zeile pro (Tag, Modell):

# Per-model daily breakdown — one row per (day, model)
curl https://api.kunavo.com/v1/usage \
  -G \
  -H "Authorization: Bearer $KUNAVO_API_KEY" \
  --data-urlencode "start_date=2026-05-01" \
  --data-urlencode "end_date=2026-05-27" \
  --data-urlencode "group_by=model"

Python — das Zeitfenster zu einer einzigen Zahl summieren:

import os, datetime as dt, requests

today = dt.date.today()
start = today - dt.timedelta(days=29)  # last 30 days inclusive

r = requests.get(
    "https://api.kunavo.com/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['KUNAVO_API_KEY']}"},
    params={
        "start_date": start.isoformat(),
        "end_date":   today.isoformat(),
        "group_by":   "model",
    },
    timeout=30,
)
r.raise_for_status()
body = r.json()

# body["data"] is one row per (day, model). Sum cost across the window:
total_usd = sum(float(row["cost_usd"]) for row in body["data"])
print(f"Spent ${total_usd:.4f} on key {body['api_key']['name']}")

Antwort

200 OK — application/json mit einer Liste von Zeilen. Zeitfenster ohne Aktivität werden weggelassen; der Client ergänzt Lücken, falls eine lückenlose Reihe benötigt wird.

{
  "object": "list",
  "api_key": {
    "id": "k_abc123",
    "name": "production",
    "prefix": "sk-kn-aZ8x"
  },
  "start_date": "2026-05-01",
  "end_date":   "2026-05-27",
  "bucket": "day",
  "data": [
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "claude-sonnet-4-6",
      "requests": 1284,
      "errors": 7,
      "input_tokens": 1532890,
      "output_tokens": 245100,
      "cached_input_tokens": 980000,
      "cache_write_tokens": 12000,
      "web_search_requests": 0,
      "cost_usd": "3.452100"
    },
    {
      "bucket_start": "2026-05-01T00:00:00.000Z",
      "model": "gpt-5",
      "requests": 88,
      "errors": 0,
      "input_tokens": 42000,
      "output_tokens": 12300,
      "cached_input_tokens": 0,
      "cache_write_tokens": 0,
      "web_search_requests": 0,
      "cost_usd": "0.210400"
    }
  ]
}

Clientseitiges Caching

Der Endpunkt setzt Cache-Control: private, max-age=60. Die meisten Clients (Browser, Anfragen mit einer Sitzung und jeder HTTP-Cache auf Ihrer Seite) geben innerhalb eines Zeitfensters von 60 Sekunden für dieselben Parameter dieselbe Antwort zurück – geeignet für regelmäßig aktualisierte Dashboards. Um eine aktuelle Antwort zu erzwingen, variieren Sie den Query-String (z. B. durch Anhängen eines &_=ts-Cache-Busters) oder übergeben Sie clientseitig Cache-Control: no-cache.

Fehler

Einschränkungen

• Gelöschte Schlüssel. Wenn Sie einen API-Schlüssel widerrufen, wird sein api_key_id in den historischen Nutzungszeilen entfernt (auf null gesetzt), sodass sich die bisherigen Summen über diesen Endpunkt nicht mehr abrufen lassen. Die Daten bleiben in der kontoweiten Gesamtansicht des Dashboards erhalten. Wenn Sie einen unveränderlichen Prüfpfad pro Schlüssel benötigen, rufen Sie die Daten vor dem Widerruf ab und speichern Sie sie.
• Nahezu in Echtzeit. Die Zeilen erscheinen wenige Sekunden nach Abschluss des zugrunde liegenden Aufrufs. Es gibt keine garantierte maximale Verzögerung. Wenn Sie eine genaue Übereinstimmung mit Ihrer Rechnung benötigen, fragen Sie einmal täglich die Daten des Vortags ab, statt minütlich.
• Die Kosten entsprechen den abgerechneten Kosten. Der Wert cost_usd entspricht hier dem Betrag, der Ihrem Wallet-Ledger belastet wurde. Er berücksichtigt bereits den max(catalog, upstream × markup)-Mindestbetrag, der unter Abrechnung beschrieben ist. Die Antwort enthält keinen separaten „Großhandelspreis“.

Nächste Schritte

• Abrechnung & Hauptbuch — wie cost_usd für jeden Aufruf berechnet wird, bevor es hier erfasst wird.
• Authentifizierung — neue API-Schlüssel erstellen (einen pro Projekt).
• Nutzungsansicht im Dashboard — dieselben Daten mit Diagrammen, Aufschlüsselung pro Aufruf und kontoweiter Zusammenfassung über alle Ihre Schlüssel hinweg.