Nutzung abrufen (get_usage)

Die Nutzung-API liefert dir eine detaillierte Aufschlüsselung deines Hi Walter API-Verbrauchs für einen gewählten Zeitraum: heute, die vergangene Woche, den vergangenen Monat oder den laufenden Abrechnungszeitraum.

Du erhältst ein tagesgenaues Protokoll der getätigten API-Aufrufe, verbrauchten Credits, erfolgreichen Treffer, leeren Ergebnisse und fehlgeschlagenen Anfragen, dazu die Summen für den Zeitraum.

Nutze diesen Endpunkt, um:

• Verbrauchstrends über die Zeit zu verfolgen
• deine Nutzung Tag für Tag zu prüfen
• interne Nutzungs-Dashboards zu bauen

POST https://api.hiwalter.de/api/v1/tools/get_usage

Anfrage

Übergib deinen API-Schlüssel als Bearer-Token im Authorization-Header. Schlüssel haben das Format hw_XXXXXXXXXXX. Der Anfrage-Body wird als application/json gesendet.

Parameter	Typ	Erforderlich	Beschreibung
period	enumstring	Nein	Zeitfenster, über das berichtet wird. Standard ist today. Verfügbare Optionen: today, week, month, billing_cycle.

Beispiel

curl --request POST \
  --url https://api.hiwalter.de/api/v1/tools/get_usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "period": "month"
  }'

Antwort

Eine erfolgreiche Anfrage liefert Status 200 mit dem Verbrauchsprotokoll unter results, den Fair-Use-Kontingenten unter metadata und dem Statusfeld status.

{
  "results": {
    "period": "today",
    "start_date": "2026-07-14",
    "end_date": "2026-07-14",
    "token_balance": -1,
    "days": [
      {
        "date": "2026-07-14",
        "calls": 2634,
        "tokens": 1405,
        "with_data": 1422,
        "without_data": 1195,
        "failed": 17
      }
    ],
    "totals": {
      "calls": 2634,
      "tokens": 1405,
      "with_data": 1422,
      "without_data": 1195,
      "failed": 17
    }
  },
  "status": "ok",
  "metadata": {
    "fair_use": {
      "records_remaining_5h": 179999,
      "records_reset_5h": "2026-07-15T18:53:16Z",
      "records_remaining_1w": 899999,
      "records_reset_1w": "2026-07-22T13:53:16Z"
    }
  }
}

Feld	Typ	Beschreibung
results.period	string	Der ausgewertete Zeitraum.
results.start_date	string	Startdatum des Zeitraums.
results.end_date	string	Enddatum des Zeitraums.
results.token_balance	number	Verbleibendes Credit-Guthaben (-1 bei unbegrenzten Plänen).
results.days	array	Tagesgenaue Einträge für den Zeitraum.
results.days[].date	string	Datum des Eintrags.
results.days[].calls	number	Anzahl der an diesem Tag getätigten API-Aufrufe.
results.days[].tokens	number	An diesem Tag verbrauchte Credits.
results.days[].with_data	number	Aufrufe mit Treffer (Ergebnis geliefert).
results.days[].without_data	number	Aufrufe ohne Treffer (leere Ergebnisse).
results.days[].failed	number	Fehlgeschlagene Anfragen.
results.totals	object	Summen über den gesamten Zeitraum (calls, tokens, with_data, without_data, failed).
status	string	Statuskennzeichen der Antwort, z. B. ok.
metadata.fair_use	object	Verbleibende Fair-Use-Kontingente samt Reset-Zeitpunkten (5-Stunden- und 1-Wochen-Fenster).

Fehler

Status	Beschreibung
400	Bad Request. Die Anfrage konnte wegen eines Client-Fehlers nicht verarbeitet werden.
401	Unauthorized. Ungültiger API-Schlüssel.
422	Invalid Input. Die Eingabe war ungültig; die Meldung beschreibt die Ursache.
429	Too Many Requests. Rate-Limit überschritten (maximal 100 Anfragen pro Sekunde).
500	Interner Fehler. Unerwarteter Verbindungsfehler.

{
  "error": "Unauthorized",
  "message": "Invalid API key."
}