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

> Use the Usage Export API to export workspace usage data as CSV or JSON.

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.

<Note>
  You can also generate these exports in the Langdock UI. See [Usage Exports](/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/api-keys
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>

Each endpoint also supports explicit output format routes:

```
POST /export/{dataType}/csv
POST /export/{dataType}/json
```

### 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"
  },
  "group_by": "model"
}
```

`group_by` is optional. Supported values depend on the export type:

| Export              | Supported `group_by` values                     |
| ------------------- | ----------------------------------------------- |
| Users               | `model`                                         |
| Agents / Assistants | `model`                                         |
| API keys            | `model`                                         |
| Models              | `source`; `deployment` for BYOK workspaces only |
| Projects            | Not 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:

```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"
    }
  }
}
```

#### JSON Response

JSON endpoints return rows directly:

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

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

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

## Endpoint Details

* [Export User Usage](/en/developer/usage-export-api/export-users)
* [Export Agent Usage](/en/developer/usage-export-api/export-agents)
* [Export API Key Usage](/en/developer/usage-export-api/export-api-keys)
* [Export Project Usage](/en/developer/usage-export-api/export-projects)
* [Export Model Usage](/en/developer/usage-export-api/export-models)

## Troubleshooting

### Common Errors

#### 400 Bad Request - Unsupported `group_by`

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

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

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

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