> ## Documentation Index
> Fetch the complete documentation index at: https://docs.langdock.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction to Usage Export

> Comprehensive guide to using the Usage Export API for exporting user, agent, project, and model usage data.

The Usage Export API provides endpoints to export usage data for users, agents, projects, and models from your workspace. Each endpoint returns a CSV file with detailed metrics for the selected date range.

<Note>
  You can also access the Usage Export in the platform directly, more on that [here](/en/admin/compliance-and-governance/usage-exports).
</Note>

## 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

<Warning>
  **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.
</Warning>

## 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/projects
POST /export/models
```

<Info>
  The `agents` and `assistants` dataTypes return the same data — `agents` is an alias. Both paths work identically.
</Info>

### Authentication

All API requests require Bearer token authentication:

```bash theme={null}
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.

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "error": "No data found",
  "message": "No usage data found for the selected period"
}
```

### Example Requests

#### Export Assistant Usage

```bash theme={null}
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

```bash theme={null}
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
* Token consumption and cost per user (**BYOK workspaces only**)
* Per-model token and cost breakdown (**BYOK workspaces only**)
* **Note**: User-specific data may be excluded due to workspace privacy settings

### Agent Export

Contains usage data for all agents in the workspace, including:

* Number of messages
* Active users
* Usage trends over time

### Project Export

Project-related usage statistics:

* Project activity
* Involved users
* Resource consumption

### Model Export

Detailed information about model usage:

* AI models used
* Request counts
* Token consumption (**BYOK workspaces only**)

## Troubleshooting

### Common Errors

#### 400 Bad Request - Export Too Large

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

<Info>
  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](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
</Info>