> ## 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.
# Usage Exports
> Export workspace usage analytics to CSV for external analysis, reporting, and compliance.
Usage exports are available to workspace administrators and provide up to 12 months of historical data across users, agents, API keys, projects, and models.
## Accessing Usage Exports
You can export usage in the Langdock UI or programmatically with the [Usage Export API](/en/developer/usage-export-api/intro-to-usage-export-api).
To export from the UI, navigate to your workspace analytics page and click the **Export** button in the top right corner.
Go to your [workspace analytics page](https://app.langdock.com/settings/workspace/analytics) in workspace settings.
Select the **Export** button located in the top right corner
Choose your data type and date range in the export dialog
Click **Generate CSV** to create and download your export file
## Export Configuration
### Data Types
Select which type of usage data to export:
* **Users** - Individual user activity, message counts, and feature usage across the selected time period
* **Agents** - Agent usage statistics, interaction counts, and performance metrics
* **API keys** - API usage and cost grouped by API key
* **Projects** - Project-level usage data
* **Models** - Model usage statistics, request counts, and BYOK token consumption data
### Date Range Options
Choose from predefined ranges or select a custom period:
* **This month** (e.g., July 2025)
* **Last month** (e.g., June 2025)
* **This week** (e.g., July 30 - August 2)
* **Last week** (e.g., July 20 - July 26)
* **Choose custom range** - Select specific start and end dates
Historical data is limited to 12 months. You cannot export data older than 12 months from the current date.
If a custom date range is too large to export at once, export one month at a time and combine the CSV files.
## Export Data Structure
Each export generates a CSV file with one row per entity for the selected time period.
Some columns are only available for workspaces using [Bring Your Own Key (BYOK)](/en/admin/byok/byok). These are marked as **BYOK workspaces only**.
## Usage Exports
The Users export provides individual user activity across the selected period.
For workspaces with user-level data disabled, certain identifying columns (like user email and name) are excluded from exports to maintain privacy compliance.
### Column Definitions
| Column | Description |
| ------------------------------ | ------------------------------------------------- |
| `period_start` | Start date of the report (YYYY-MM-DD, UTC) |
| `period_end` | End date of the report (YYYY-MM-DD, UTC) |
| `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 at the time of export |
| `joined_at` | Date the user joined the workspace |
| `department` | User department |
| `company_name` | User company name |
| `license_type` | Current user 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 |
### Subgroup Rows
In the export dialog, use **Subgroup rows** to split each user into one row per model they used. Choose **No grouping** to keep one row per user.
When subgrouped by **Model**, ranking, JSON breakdown, and action columns are omitted, as is `projects_messaged`.
***
The Agents export shows usage statistics for each agent.
For workspaces with user-level data disabled, certain identifying columns (like user email and name) are excluded from exports to maintain privacy compliance.
### Column Definitions
| Column | Description |
| ----------------------- | ---------------------------------------------------- |
| `period_start` | Start date of the report |
| `period_end` | End date of the report |
| `org_id` | ID of the workspace |
| `assistant_id` | ID of the agent |
| `assistant_name` | Name of the agent |
| `assistant_description` | Agent description |
| `assistant_url` | Link to the agent |
| `assistant_owner_id` | ID of the agent owner |
| `assistant_owner_email` | Email of the agent owner |
| `messages` | Number of user messages sent to the agent |
| `unique_users` | Number of users who messaged the agent |
| `active_users` | Number of active users from the agent analytics KPI |
| `conversations` | Number of conversations from the agent analytics KPI |
| `messages_per_user` | Average messages per active user |
### Additional Columns for BYOK Workspaces
| Column | Description |
| --------------------------- | -------------------------------------------- |
| `sum_prompt_tokens` | Total input tokens |
| `avg_prompt_tokens` | Average input tokens per request |
| `min_prompt_tokens` | Minimum input tokens per request |
| `max_prompt_tokens` | Maximum input tokens per request |
| `sum_completion_tokens` | Total output tokens |
| `avg_completion_tokens` | Average output tokens per request |
| `min_completion_tokens` | Minimum output tokens per request |
| `max_completion_tokens` | Maximum output tokens per request |
| `sum_cached_prompt_tokens` | Cache-read input tokens |
| `sum_cache_creation_tokens` | Cache-write input tokens |
| `sum_no_cache_tokens` | Input tokens that were not served from cache |
### Subgroup Rows
In the export dialog, use **Subgroup rows** to split each agent into one row per model used by that agent. Choose **No grouping** to keep one row per agent.
When subgrouped by **Model**, agent-level KPI fields (`active_users`, `conversations`, `messages_per_user`) are omitted.
***
The API Keys export shows usage and cost by API key.
| Column | Description |
| ---------------- | ------------------------ |
| `period_start` | Start date of the report |
| `period_end` | End date of the report |
| `org_id` | ID of the workspace |
| `api_key_id` | ID of the API key |
| `api_key_name` | Name of the API key |
| `requests` | Number of API requests |
| `total_cost_usd` | API usage cost in USD |
### Additional Columns for BYOK Workspaces
| Column | Description |
| ----------------------- | -------------------------------------------- |
| `sum_prompt_tokens` | Total input tokens |
| `sum_completion_tokens` | Total output tokens |
| `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 |
### Subgroup Rows
In the export dialog, use **Subgroup rows** to split each API key into one row per model used through that key. Choose **No grouping** to keep one row per API key.
***
The Projects export shows usage data for collaborative projects in your workspace.
For workspaces with user-level data disabled, certain identifying columns (like user email and name) are excluded from exports to maintain privacy compliance.
### Column Definitions
| Column | Description |
| --------------------- | ----------------------------------- |
| `period_start` | Start date of the report |
| `period_end` | End date of the report |
| `org_id` | ID of the workspace |
| `project_id` | ID of the project |
| `project_name` | Name of the project |
| `project_owner_id` | ID of the project owner |
| `project_owner_email` | Email of the project owner |
| `messages` | Number of messages in project chats |
The Models export provides usage statistics for each AI model used in your workspace.
### Column Definitions
| Column | Description |
| ----------------- | ------------------------------------ |
| `period_start` | Start date of the report |
| `period_end` | End date of the report |
| `org_id` | ID of the workspace |
| `name` | Normalized model name |
| `provider` | Model provider |
| `bring_your_keys` | Whether usage came from a BYOK model |
| `requests` | Number of requests |
### Additional Columns for BYOK Workspaces
| Column | Description |
| --------------------------- | -------------------------------------------- |
| `sum_prompt_tokens` | Total input tokens |
| `sum_completion_tokens` | Total output tokens |
| `sum_cached_prompt_tokens` | Cache-read input tokens |
| `sum_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 |
### Subgroup Rows
In the export dialog, use **Subgroup rows** to split model usage into more detailed rows. Choose **No grouping** to keep one row per normalized model name, provider, and BYOK state.
Available subgroup options:
* **Source** - one row per model and source, such as `WEB` or `MOBILE`
* **Deployment** - one row per model and deployment; available for BYOK workspaces only
***
## Actions Referenced in User Export
The following actions may appear in the `action_to_messages` column of the Users export:
Used to edit documents and code in a structured interface. Messages represent user prompts that trigger Canvas interactions (creation, querying, deletion).
Used to search external web sources for real-time information. Messages represent user prompts that trigger web search functionality.
Used to analyze uploaded documents, spreadsheets, and other file types. Messages represent user prompts that trigger file processing and analysis.
Used to run and test code in various programming languages. Messages represent user prompts that trigger code execution requests.
Actions from connected integrations (e.g., `Hubspot_create_contact`, `Slack_send_message`). Messages represent user prompts that trigger API calls to external services through Langdock integrations.
## Data Handling and Privacy
### Null Values
Empty or unavailable data fields are handled as follows:
* Numeric fields: Display as `0` or empty
* Text fields: Display as empty strings
* JSON objects: Display as empty objects `{}`
### Data Retention
* Historical data is available for up to 12 months
* Export data reflects the state at the time of export
* User roles, names, and other attributes show values as of the period end date