Zum Hauptinhalt springen
Die Usage Export API bietet fünf Endpunkte, um Nutzungsdaten für Nutzer, Assistenten, Workflows, Projekte und Modelle aus deinem Workspace zu exportieren. Jeder Endpunkt gibt einen CSV Datei mit detaillierten Metriken für den gewählten Zeitraum zurück.
Du kannst den Nutzungsexport auch direkt in der Plattform aufrufen, mehr dazu hier.

​
Voraussetzungen

Um die Usage Export API zu nutzen, benötigst du:
  • Workspace Admin-Berechtigung: Nur Workspace-Administratoren können API-Schlüssel mit Nutzungsexport-Berechtigungen erstellen und Daten über das Web-Interface exportieren.
  • API-Schlüssel mit USAGE_EXPORT_API Scope: Spezielle Berechtigung für den Zugriff auf Export-Funktionen
Wichtiger Sicherheitshinweis: Nutzer mit Zugriff auf einen API-Schlüssel mit USAGE_EXPORT_API Scope können Workspace-Nutzungsdaten für alle Bereiche exportieren, auch wenn sie normalerweise keinen Zugriff haben, diese Daten einzusehen. Gewähre diese Berechtigung nur vertrauenswürdigen Nutzern.

​
Programmatischer Export

​
Verfügbare Endpunkte

Die Usage Export API bietet Zugriff auf verschiedene Datentypen: 
POST /api/public/export/users
POST /api/public/export/assistants
POST /api/public/export/workflows
POST /api/public/export/projects
POST /api/public/export/models

​
Authentifizierung

Alle API-Anfragen erfordern Bearer Token-Authentifizierung: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Anfrage-Format

{
  "from": {
    "date": "2024-01-01T00:00:00.000Z",
    "timezone": "UTC"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999Z",
    "timezone": "UTC"
  }
}

​
Antwort-Format

​
Erfolgreiche Antwort

{
  "success": true,
  "data": {
    "filePath": "assistants-usage/workspace-id/assistants-usage-2024-01-01-2024-01-31-abc12345.csv",
    "downloadUrl": "https://storage.example.com/signed-url",
    "dataType": "assistants",
    "recordCount": 1250,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000Z",
      "to": "2024-01-31T23:59:59.999Z"
    }
  }
}

​
Fehler-Antwort

{
  "error": "No data found",
  "message": "No usage data found for the selected period"
}

​
Beispiel-Anfragen

​
Assistenten-Nutzung exportieren

curl -X POST "https://api.langdock.com/api/public/export/assistants" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000Z",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999Z",
      "timezone": "UTC"
    }
  }'

​
Nutzer-Nutzung exportieren

curl -X POST "https://api.langdock.com/api/public/export/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000Z",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999Z",
      "timezone": "UTC"
    }
  }'

​
Rate Limits

Die Usage Export API unterliegt denselben Rate Limits wie andere API-Endpunkte:
  • Tokens pro Minute: 60.000 Tokens/Min
  • Anfragen pro Minute: 500 Anfragen/Min

​
Export-Größenlimits

Exporte sind auf 1.000.000 Zeilen begrenzt. Wenn dein Export dieses Limit überschreitet, erhältst du einen 400-Fehler mit der Bitte, den Datumsbereich einzugrenzen.

​
Datentypen im Detail

​
Nutzer-Export

Zeigt individuelle Nutzeraktivität, abhängig von Datenschutzeinstellungen:
  • Nachrichtenzahl pro Nutzer
  • Aktivitätsmuster
  • Hinweis: Nutzerspezifische Daten können aufgrund von Workspace-Datenschutzeinstellungen ausgeschlossen sein

​
Assistenten-Export

Enthält Nutzungsdaten für alle Assistenten im Workspace, einschließlich:
  • Anzahl der Nachrichten
  • Aktive Nutzer
  • Nutzungstrends über Zeit

​
Workflow-Export

Nutzungsdaten für Workflows (falls aktiviert):
  • Workflow-Ausführungen
  • Erfolgsraten
  • Performance-Metriken

​
Projekt-Export

Projektbezogene Nutzungsstatistiken:
  • Projektaktivität
  • Beteiligte Nutzer
  • Ressourcenverbrauch

​
Modell-Export

Detaillierte Informationen zur Modellnutzung:
  • Verwendete KI-Modelle
  • Token-Verbrauch
  • Kosten pro Modell

​
Fehlerbehebung

​
Häufige Fehler

​
400 Bad Request - Export zu groß

{
  "error": "Export too large",
  "message": "Export too large: 1500000 rows exceeds limit of 1000000. Please narrow the date range."
}
Lösung: Reduziere den Zeitraum deiner Anfrage oder teile den Export in kleinere Zeitbereiche auf.

​
401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
Lösung: Überprüfe, ob dein API-Schlüssel korrekt ist und die USAGE_EXPORT_API-Berechtigung hat.

​
404 Keine Daten gefunden

{
  "error": "No data found",
  "message": "No usage data found for the selected period"
}
Lösung: Überprüfe den gewählten Zeitraum - möglicherweise gab es in diesem Zeitraum keine Aktivität.

​
Sicherheit und Datenschutz

​
Datenschutzeinstellungen

Abhängig von der Workspace-Konfiguration können bestimmte Daten ausgeschlossen werden:
  • Nutzeridentifizierende Daten: Können aufgrund von Datenschutzeinstellungen ausgeschlossen sein
  • Leaderboards: Müssen im Workspace aktiviert sein, um vollständige Nutzerdaten zu erhalten

​
Best Practices

  1. Sichere API-Schlüssel-Speicherung: Verwende Umgebungsvariablen oder sichere Schlüsselverwaltung
  2. Regelmäßige Rotation: Erneuere API-Schlüssel regelmäßig
  3. Minimale Berechtigungen: Gewähre nur notwendige Scopes
  4. Monitoring: Überwache die Nutzung deiner API-Schlüssel

​
Compliance

Die Usage Export API hilft bei Compliance-Anforderungen:
  • Audit Trails: Vollständige Nachverfolgung der API-Nutzung
  • Datenexport: Unterstützung für DSGVO-Datenzugriffsrechte
  • Transparenz: Klare Einblicke in die Workspace-Nutzung

​
Support

Bei Fragen zur Usage Export API wende dich an unser Support-Team oder konsultiere die vollständige API-Dokumentation.
⌘I