Skip to main content
The Usage Export API provides five endpoints to export usage data for users, assistants, workflows, projects, and models from your workspace. Each endpoint returns a CSV file with detailed metrics for the selected date range.
You can also access the Usage Export in the platform directly, more on that here.

​
Prerequisites

To use the Usage Export API, you need:
  • Workspace Admin Permission: Only workspace administrators can create API keys with usage export permissions and export data via the web interface.
  • API Key with USAGE_EXPORT_API Scope: Special permission for accessing export functions
Important Security Notice: Users with access to an API key with USAGE_EXPORT_API scope can export workspace usage data for all areas, even if they normally don’t have access to view this data. Only grant this permission to trusted users.

​
Programmatic Export

​
Available Endpoints

The Usage Export API provides access to various data types: 
POST /export/users
POST /export/assistants
POST /export/workflows
POST /export/projects
POST /export/models

​
Authentication

All API requests require Bearer token authentication: 
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Request Format

Time specification and time zone handling:
The API uses the exact time included in the date parameter you provide & treats them as your local times, specified in the timezone parameter. If you include a “Z” at the end of your date (which stands for UTC/Zulu time), it automatically removes it to prevent the timezone from being applied twice. 
{
  "from": {
    "date": "2024-01-01T00:00:00.000",
    "timezone": "Europe/Berlin"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999", 
    "timezone": "UTC"
  }
}

​
Response Format

​
Successful Response

The dates are returned in the correct timezone format with the proper time offset (e.g., +01:00/+02:00 for Berlin) 
{
  "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"
    }
  }
}

​
Error Response

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

​
Example Requests

​
Export Assistant Usage

curl -X POST "https://api.langdock.com/export/assistants" \
  -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"
    }
  }'

​
Export User Usage

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

The Usage Export API is subject to the same rate limits as other API endpoints:
  • Tokens per Minute: 60.000 Tokens/Min
  • Requests per Minute: 500 Requests/Min

​
Export Size Limits

Exports are limited to 1,000,000 rows. If your export exceeds this limit, you’ll receive a 400 error asking you to narrow the date range.

​
Data Types in Detail

​
User Export

Shows individual user activity, depending on privacy settings:
  • Message count per user
  • Activity patterns
  • Note: User-specific data may be excluded due to workspace privacy settings

​
Assistant Export

Contains usage data for all assistants in the workspace, including:
  • Number of messages
  • Active users
  • Usage trends over time

​
Workflow Export

Usage data for workflows (if enabled):
  • Workflow executions
  • Success rates
  • Performance metrics

​
Project Export

Project-related usage statistics:
  • Project activity
  • Involved users
  • Resource consumption

​
Model Export

Detailed information about model usage:
  • AI models used
  • Token consumption
  • Cost per model

​
Troubleshooting

​
Common Errors

​
400 Bad Request - Export Too Large

{
  "error": "Export too large",
  "message": "Export too large: 1500000 rows exceeds limit of 1000000. Please narrow the date range."
}
Solution: Reduce the time period of your request or split the export into smaller time ranges.

​
401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
Solution: Check that your API key is correct and has the USAGE_EXPORT_API permission.

​
404 No Data Found

{
  "error": "No data found", 
  "message": "No usage data found for the selected period"
}
Solution: Check the selected time period - there may have been no activity during this period.

​
Security and Privacy

​
Privacy Settings

Depending on workspace configuration, certain data may be excluded:
  • User-identifying Data: May be excluded due to privacy settings
  • Leaderboards: Must be enabled in the workspace to get complete user data

​
Best Practices

  1. Secure API Key Storage: Use environment variables or secure key management
  2. Regular Rotation: Renew API keys regularly
  3. Minimal Permissions: Only grant necessary scopes
  4. Monitoring: Monitor the usage of your API keys

​
Compliance

The Usage Export API helps with compliance requirements:
  • Audit Trails: Complete tracking of API usage
  • Data Export: Support for GDPR data access rights
  • Transparency: Clear insights into workspace usage

​
Support

For questions about the Usage Export API, contact our support team or consult the complete API documentation.