Mit der Usage Export API können Workspace-Administratoren Nutzungsdaten für Nutzer, Agenten, API-Schlüssel, Projekte und Modelle exportieren. Nutze sie, wenn du Berichte automatisieren oder Daten in ein externes Analytics-System übertragen möchtest.
Du kannst diese Exporte auch direkt in der Langdock-Oberfläche erstellen. Mehr dazu findest du unter Nutzungsexporte. Voraussetzungen
Um die Usage Export API zu nutzen, benötigst du:
- Workspace-Admin-Berechtigung: Nur Workspace-Administratoren können API-Schlüssel mit Nutzungsexport-Berechtigung erstellen.
- API-Schlüssel mit
USAGE_EXPORT_API Scope: Spezielle Berechtigung für den Zugriff auf Nutzungsexporte.
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 diese Daten normalerweise nicht in der Oberfläche sehen können. Gewähre diese Berechtigung nur vertrauenswürdigen Personen.
Programmatischer Export
Verfügbare Endpunkte
POST /export/users
POST /export/assistants
POST /export/agents
POST /export/api-keys
POST /export/projects
POST /export/models
agents und assistants geben die gleichen Daten zurück. agents ist ein Alias.
POST /export/{dataType}/csv
POST /export/{dataType}/json
Authentifizierung
Alle Anfragen benötigen Bearer-Token-Authentifizierung:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
date-Wert und interpretiert sie in der angegebenen timezone. Wenn du ein Z am Ende des date-Werts angibst, entfernt Langdock dieses automatisch, damit die Zeitzone nicht doppelt angewendet wird.
{
"from": {
"date": "2024-01-01T00:00:00.000",
"timezone": "Europe/Berlin"
},
"to": {
"date": "2024-01-31T23:59:59.999",
"timezone": "UTC"
},
"group_by": "model"
}
group_by ist optional. Unterstützte Werte hängen vom Exporttyp ab:
| Export | Unterstützte group_by-Werte |
|---|
| Nutzer | model |
| Agenten / Assistants | model |
| API-Schlüssel | model |
| Modelle | source; deployment nur für BYOK-Workspaces |
| Projekte | Nicht unterstützt |
CSV-Antwort
CSV-Endpunkte geben einen Dateipfad und eine Download-URL zurück:
{
"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.000+01:00",
"to": "2024-01-31T23:59:59.999"
}
}
}
JSON-Antwort
JSON-Endpunkte geben die Zeilen direkt zurück:
{
"success": true,
"data": [
{
"period_start": "2024-01-01",
"period_end": "2024-01-31",
"org_id": "workspace-id"
}
],
"metadata": {
"dataType": "users",
"recordCount": 1,
"dateRange": {
"from": "2024-01-01T00:00:00.000Z",
"to": "2024-01-31T23:59:59.999Z"
}
}
}
Fehlerantwort
{
"message": "No usage data found for the selected period",
"code": "NOT_FOUND"
}
Beispielanfrage
curl -X POST "https://api.langdock.com/export/users" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": {
"date": "2024-01-01T00:00:00.000",
"timezone": "UTC"
},
"to": {
"date": "2024-01-31T23:59:59.999",
"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
Details zu Endpunkten
Sicherheit und Datenschutz
Langdock blockiert bewusst Browser-basierte Anfragen, um deinen API-Schlüssel zu schützen. Verwende API-Schlüssel serverseitig und speichere sie sicher. Mehr dazu findest du unter Best Practices für API-Schlüssel. 
