> ## 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.
# Export User Usage
> API endpoint to export user activity data including message counts and usage patterns (subject to privacy settings)
This endpoint exports user activity data including message counts, usage patterns, and feature utilization. The available data depends on your workspace privacy settings.
**Using a dedicated deployment?**
Replace `api.langdock.com` with `/api/public` in all requests.
For details on prerequisites and rate limits, please refer to the [main Usage Export API documentation](/en/developer/usage-export-api/intro-to-usage-export-api).
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).
## Privacy Considerations
The user export data is subject to workspace privacy settings, **user-identifying data** may be excluded due to privacy settings. As a consequence of this some data may be anonymized based on workspace configuration.
## Data Included
By default, the user export returns one row per user for the selected period.
| Column | Description |
| ------------------------------ | ------------------------------------------------- |
| `period_start` | Start date of the report |
| `period_end` | End date of the report |
| `org_id` | ID of the workspace |
| `user_id` | ID of the user |
| `name` | Name of the user |
| `email` | Email of the user |
| `role` | User role |
| `joined_at` | Date the user joined the workspace |
| `department` | User department |
| `company_name` | User company name |
| `license_type` | Current license tier |
| `payg_limit_current` | Current extra-usage limit |
| `payg_consumption_in_period` | Extra-usage consumption in the selected period |
| `payg_utilization_pct_current` | `payg_consumption_in_period / payg_limit_current` |
| `messages_total` | Total messages sent by the user |
| `messages_total_rank` | Rank by total messages |
| `messages_chat` | Messages sent in regular chats |
| `messages_chat_rank` | Rank by chat messages |
| `messages_assistants` | Messages sent to agents |
| `messages_assistants_rank` | Rank by agent messages |
| `assistants_messaged` | Number of distinct agents messaged |
| `assistants_to_messages` | JSON mapping agent ID to message count |
| `messages_projects` | Messages sent to projects |
| `messages_projects_rank` | Rank by project messages |
| `projects_messaged` | Number of distinct projects messaged |
| `projects_to_messages` | JSON mapping project ID to message count |
| `model_to_messages_total` | JSON mapping model name to message count |
| `action_messages` | Messages generated by actions |
| `action_messaged` | Number of distinct actions triggered |
| `action_to_messages` | JSON mapping action name to message count |
### Additional Columns for BYOK Workspaces
| Column | Description |
| ----------------------- | -------------------------------------------- |
| `total_input_tokens` | Total input tokens consumed by the user |
| `total_output_tokens` | Total output tokens generated for the user |
| `cached_prompt_tokens` | Cache-read input tokens |
| `cache_creation_tokens` | Cache-write input tokens |
| `no_cache_tokens` | Input tokens that were not served from cache |
| `total_cost_usd` | Estimated provider cost in USD |
Because BYOK workspaces supply their own model keys, Langdock can provide token consumption and costs directly. This is not possible when obtaining your models directly through Langdock.
### Grouped Export
Use `group_by=model` to return one row per user and model.
## OpenAPI
````yaml POST /export/users
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/export/users:
post:
tags:
- Usage Export
summary: Export user usage data
description: >-
Export detailed usage data for all users in the workspace (subject to
privacy settings)
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportModelGroupByRequest'
responses:
'200':
description: Export successful
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
'404':
description: No data found
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
components:
schemas:
UsageExportModelGroupByRequest:
allOf:
- $ref: '#/components/schemas/UsageExportRequest'
- type: object
properties:
group_by:
type: string
description: Optional aggregation dimension.
enum:
- model
UsageExportResponse:
type: object
description: Successful response from usage export endpoints
properties:
success:
type: boolean
description: Indicates if the export was successful
example: true
data:
type: object
description: Export data information
properties:
filePath:
type: string
description: Path to the generated export file
example: >-
agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv
downloadUrl:
type: string
format: uri
description: Signed URL to download the export file
example: https://storage.example.com/signed-url
dataType:
type: string
description: Type of data exported
enum:
- assistants
- agents
- api_keys
- users
- projects
- models
example: assistants
recordCount:
type: integer
description: Number of records in the export
example: 1250
dateRange:
type: object
description: Actual date range of the exported data
properties:
from:
type: string
format: date-time
description: Start date of the export
example: '2024-01-01T00:00:00.000Z'
to:
type: string
format: date-time
description: End date of the export
example: '2024-01-31T23:59:59.999Z'
required:
- from
- to
required:
- filePath
- downloadUrl
- dataType
- recordCount
- dateRange
required:
- success
- data
UsageExportError:
type: object
description: Error response from usage export endpoints
properties:
error:
type: string
description: Error type
example: No data found
message:
type: string
description: Detailed error message
example: No usage data found for the selected period
required:
- error
- message
UsageExportRequest:
type: object
description: Request body for usage export endpoints
properties:
from:
type: object
description: Start date and timezone for the export
properties:
date:
type: string
format: date-time
description: Start date in ISO 8601 format
example: '2024-01-01T00:00:00.000Z'
timezone:
type: string
description: Timezone for the date range
example: UTC
required:
- date
- timezone
to:
type: object
description: End date and timezone for the export
properties:
date:
type: string
format: date-time
description: End date in ISO 8601 format
example: '2024-01-31T23:59:59.999Z'
timezone:
type: string
description: Timezone for the date range
example: UTC
required:
- date
- timezone
required:
- from
- to
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````