Skip to main content
The Usage Export API lets workspace administrators export usage data for users, agents, API keys, projects, and models. Use it when you want to automate reporting or pull data into an external analytics system.
You can also generate these exports in the Langdock UI. See Usage Exports.

​
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/agents
POST /export/api-keys
POST /export/projects
POST /export/models
The agents and assistants dataTypes return the same data — agents is an alias. Both paths work identically.
Each endpoint also supports explicit output format routes: 
POST /export/{dataType}/csv
POST /export/{dataType}/json

​
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"
  },
  "group_by": "model"
}
group_by is optional. Supported values depend on the export type:
ExportSupported group_by values
Usersmodel
Agents / Assistantsmodel
API keysmodel
Modelssource; deployment for BYOK workspaces only
ProjectsNot supported
Requests with an unsupported group_by value return a 400 Bad Request.

​
Response Format

​
CSV Response

CSV endpoints return a file path and download URL: 
{
  "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 Response

JSON endpoints return rows directly: 
{
  "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"
    }
  }
}

​
Error Response

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

​
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

​
Endpoint Details

​
Troubleshooting

​
Common Errors

​
400 Bad Request - Unsupported group_by

{
  "message": "group_by=deployment is not supported for users exports",
  "code": "BAD_REQUEST"
}
Solution: Use a group_by value supported by the export type, or omit the field.

​
401 Unauthorized

{
  "message": "The provided API key is invalid."
}
Solution: Check that your API key is correct and has the USAGE_EXPORT_API permission.

​
404 No Data Found

{
  "message": "No usage data found for the selected period",
  "code": "NOT_FOUND"
}
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.
Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.