Introduction to Usage Export

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: https://docs.langdock.com/admin/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

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.

Example request body:

{
  "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

Dates are returned in the correct timezone format with the proper time offset (e.g., +01:00/+02:00 for Berlin).

Example successful response:

{
  "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

Example error response:

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

Example Requests

Export Assistant Usage

curl

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

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

• 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

Example response:

{
  "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

Example response:

{
  "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

Example response:

{
  "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.

Related links

• Search through all files in data folders shared with the API Key: https://docs.langdock.com/api-endpoints/knowledge-folder/search-knowledge-folder

• Export User Usage: https://docs.langdock.com/api-endpoints/usage-export/export-users