> ## 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 detailed usage analytics from your Langdock workspace to CSV format for external analysis, reporting, and compliance purposes.
Usage exports are available to workspace administrators and provide up to 12 months of historical data across users, agents, projects, and models.
## Accessing Usage Exports
Navigate to your workspace analytics page and click the **Export** button in the top right corner to open the export configuration dialog.
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
* **Projects** - Project-level usage data
* **Models** - Model usage statistics and 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.
## Export Data Structure
Each export generates a CSV file with one row per entity (user, agent, project, or model) and columns containing relevant metrics for the selected time period.
Some columns in the exports below are only available for workspaces using [Bring Your Own Key (BYOK)](/en/admin/byok/byok). These are marked as **BYOK workspaces only** in the column definitions.
## Usage Exports
The Users export provides data about individual user activity within 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 (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` | Role of the user (member, editor, or admin) at the time of the export |
| `joined_at` | Date the user joined the workspace (YYYY-MM-DD, UTC) |
| `messages_total` | Total number of messages the user has sent in the period |
| `messages_total_rank` | Relative position of the user in a list of all workspace users sorted by total messages in the period (1 = most messages) |
| `messages_chat` | Number of messages the user has sent in regular chats in the period |
| `messages_chat_rank` | Relative position of the user in a list of all workspace users sorted by chat messages in the period (1 = most messages) |
| `messages_agents` | Number of messages the user has sent to agent chats in the period |
| `messages_agents_rank` | Relative position of the user in a list of all workspace users sorted by agent messages in the period (1 = most messages) |
| `agents_messaged` | Number of distinct agents the user messaged in the period |
| `agents_to_messages` | JSON object mapping agent\_id to messages\_count for each agent the user messaged in the period |
| `messages_projects` | Number of messages the user has sent to project chats in the period |
| `messages_projects_rank` | Relative position of the user in a list of all workspace users sorted by project messages in the period (1 = most messages) |
| `projects_messaged` | Number of distinct projects the user messaged in the period |
| `projects_to_messages` | JSON object mapping project\_id to messages\_count for each project the user messaged in the period |
| `model_to_messages_total` | JSON object mapping model\_name to messages\_count for each model the user messaged in the period |
| `action_messages` | Number of messages from the user generated by actions in the period |
| `action_messaged` | Number of distinct actions the user triggered in the period |
| `action_to_messages` | JSON object mapping action\_name to messages\_count for each action the user triggered in the period. Actions include capabilities like Canvas or Web Search as well as actions from integrations |
### Additional Columns for BYOK Workspaces
| Column | Description |
| ------------------------ | --------------------------------------------------------------- |
| `total_input_tokens` | Total input tokens consumed by the user in the period. |
| `total_output_tokens` | Total output tokens generated for the user in the period. |
| `total_cost_usd` | Total estimated cost in USD for the user in the period. |
| `model_to_input_tokens` | JSON object mapping model name to input token count per model. |
| `model_to_output_tokens` | JSON object mapping model name to output token count per model. |
| `model_to_cost_usd` | JSON object mapping model name to cost in USD per model. |
***
The Agents export shows usage statistics for each agent 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 (YYYY-MM-DD, UTC) |
| `period_end` | End date of the report (YYYY-MM-DD, UTC) |
| `org_id` | ID of the workspace |
| `agent_id` | ID of the agent |
| `agent_name` | Name of the agent at the time of the export |
| `agent_description` | Description of the agent at the time of the export |
| `agent_url` | URL of the agent |
| `agent_owner_id` | ID of the user who is the owner of the agent at the time of the export |
| `agent_owner_email` | Email of the user who is the owner of the agent at the time of the export |
| `messages` | Number of messages sent to this agent in the period |
| `unique_users` | Number of distinct users who sent at least 1 message to this agent in the period |
### Additional Columns for BYOK Workspaces
| Column | Description |
| ----------------------- | ---------------------------------------------------------------------------------- |
| `sum_prompt_tokens` | Sum of all prompt tokens used by this agent in the period. |
| `avg_prompt_tokens` | Average number of prompt tokens per request for this agent in the period. |
| `min_prompt_tokens` | Smallest number of prompt tokens used per request by this agent in the period. |
| `max_prompt_tokens` | Largest number of prompt tokens used per request by this agent in the period. |
| `sum_completion_tokens` | Total completion tokens used by this agent in the period. |
| `avg_completion_tokens` | Average number of completion tokens used per request by this agent in the period. |
| `min_completion_tokens` | Smallest number of completion tokens used per request by this agent in the period. |
| `max_completion_tokens` | Largest number of completion tokens used per request by this agent in the period. |
***
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 (YYYY-MM-DD, UTC) |
| `period_end` | End date of the report (YYYY-MM-DD, UTC) |
| `org_id` | ID of the workspace |
| `project_id` | ID of the project |
| `project_name` | Name of the project at the time of the export |
| `project_owner_id` | ID of the user who is the owner of the project |
| `project_owner_email` | Email of the user who is the owner of the project |
| `messages` | Number of messages within chats of the project in the period |
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 (YYYY-MM-DD, UTC) |
| `period_end` | End date of the report (YYYY-MM-DD, UTC) |
| `org_id` | ID of the workspace |
| `name` | Name of the model at the time of the export |
| `requests` | Number of requests sent to this model across all products in the period |
### Additional Columns for BYOK Workspaces
| Column | Description |
| ----------------------- | -------------------------------------------------------------------- |
| `sum_prompt_tokens` | Sum of all prompt tokens sent to this model in the period. |
| `sum_completion_tokens` | Sum of all completions tokens generated by this model in the period. |
***
## 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