Skip to content
ClawHosters ClawHosters
Anmelden Jetzt starten
Abo -25% LAUNCH-SUB
Claws -25% LAUNCH-CLAWS

API: Instanzen auflisten

3 min Lesezeit API Zuletzt aktualisiert 10. February 2026

Endpunkt

text 
GET /api/v1/instances

Gibt alle Instanzen des authentifizierten Kunden zurück.

Authentifizierung

Füge deinen API-Schlüssel im Authorization-Header hinzu:

text 
Authorization: Bearer oc_live_dein_api_schlüssel

Siehe API-Übersicht für Details zum Erstellen und Verwalten von API-Schlüsseln.

Anfrage

Es sind kein Request-Body und keine Query-Parameter erforderlich. Der Endpunkt gibt alle Instanzen des authentifizierten Kunden zurück.

Beispiel:

bash 
curl -X GET https://clawhosters.com/api/v1/instances \
  -H "Authorization: Bearer oc_live_dein_api_schlüssel" \
  -H "Content-Type: application/json"

Antwort

Erfolg (200 OK)

Die Antwort enthält ein data-Array mit einem Objekt pro Instanz.

json 
{
  "data": [
    {
      "id": 1,
      "name": "my-ai-bot",
      "status": "running",
      "tier": "balanced",
      "billing_mode": "daily",
      "ip_address": "2a01:4f9:0:0::abcd:1234",
      "health_status": "healthy",
      "created_at": "2026-02-05T12:34:56Z",
      "provisioned_at": "2026-02-05T12:40:22Z"
    },
    {
      "id": 2,
      "name": "experimental-setup",
      "status": "pending_configuration",
      "tier": "budget",
      "billing_mode": "monthly",
      "ip_address": "2a01:4f9:0:0::abcd:5678",
      "health_status": "unknown",
      "created_at": "2026-02-08T08:15:10Z",
      "provisioned_at": null
    }
  ]
}

Wenn du keine Instanzen hast, ist das data-Array leer:

json 
{
  "data": []
}

Antwort-Felder

Feld Typ Beschreibung
id integer Eindeutige Instanz-ID
name string Instanzname, der bei der Erstellung vergeben wurde
status string Aktueller Instanz-Status (siehe unten)
tier string Instanz-Tier: budget, balanced oder pro
billing_mode string daily (Claws) oder monthly (Stripe-Abonnement)
ip_address string IPv6-Adresse der VPS. Null, wenn noch nicht bereitgestellt
health_status string healthy, unhealthy oder unknown
created_at string ISO-8601-Zeitstempel der Erstellung
provisioned_at string oder null ISO-8601-Zeitstempel, wann die Instanz betriebsbereit wurde. Null, wenn noch nicht bereitgestellt

Instanz-Status

Status Beschreibung
provisioning VPS wird auf Hetzner Cloud erstellt
deploying Anwendung wird auf der VPS bereitgestellt
deploy_failed Deployment nach Wiederholungsversuchen fehlgeschlagen
pending_configuration Instanz läuft, wartet aber auf LLM-Konfiguration
running Instanz ist betriebsbereit und gesund
stopped Instanz ist ausgeschaltet
paused Instanz wurde pausiert (unzureichendes Claws-Guthaben oder manuell pausiert). Daten sind in einem Snapshot gesichert
error Instanz befindet sich in einem Fehlerzustand
deleting Instanz wird gerade gelöscht

Fehlerantworten

Nicht autorisiert (401)

Wird zurückgegeben, wenn der API-Schlüssel fehlt, ungültig oder widerrufen ist.

json 
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Rate-Limit überschritten (429)

Wird zurückgegeben, wenn du 100 Anfragen pro Minute überschreitest.

json 
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 42 seconds."
  }
}

Prüfe die Header X-RateLimit-Remaining und X-RateLimit-Reset, um deine Anfragerate zu steuern.

Rate-Limiting

Header Beschreibung
X-RateLimit-Limit Maximale Anfragen pro Minute (100)
X-RateLimit-Remaining Verbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-Reset Unix-Zeitstempel, wann das Zeitfenster zurückgesetzt wird

Hinweise

  • Der Endpunkt gibt alle Instanzen des authentifizierten Kunden zurück. Gelöschte Instanzen werden ausgeschlossen.
  • Zeitstempel sind in UTC und im ISO-8601-Format.
  • Das Feld ip_address kann null sein für Instanzen, die noch bereitgestellt werden oder die pausiert wurden (VPS wurde als Snapshot gesichert und der Server gelöscht).
  • Der health_status spiegelt den letzten Gesundheitscheck wider. Er kann unknown anzeigen für Instanzen, die noch nicht laufen.

Verwandte Dokumentation

Verwandte Dokumentation

API: Instanz-Details abrufen

Endpunkt text Copy GET /api/v1/instances/:id Gibt detaillierte In...

API: Instanz-Aktionen (Start/Stop/Neustart)

Überblick Steuere den Power-Status deiner Instanz über diese Endpunkte. Jede Aktion ändert den I...

API-Übersicht

Einführung Die ClawHosters-API ermöglicht es dir, deine Instanzen zu verwalten, Abrechnungen ein...