Usage Exports

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. To export from the UI, navigate to your workspace analytics page and click the Export button in the top right corner.

Open Analytics

Go to your workspace analytics page in workspace settings.

Click Export

Select the Export button located in the top right corner

Configure Export

Choose your data type and date range in the export dialog

Generate CSV

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.

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). These are marked as BYOK workspaces only.

Usage Exports

Users
Agents
API Keys
Projects
Models

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:

Canvas

Used to edit documents and code in a structured interface. Messages represent user prompts that trigger Canvas interactions (creation, querying, deletion).

Web Search

Used to search external web sources for real-time information. Messages represent user prompts that trigger web search functionality.

File Analysis

Used to analyze uploaded documents, spreadsheets, and other file types. Messages represent user prompts that trigger file processing and analysis.

Code Execution

Used to run and test code in various programming languages. Messages represent user prompts that trigger code execution requests.

Integration Actions

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

​Accessing Usage Exports

​Export Configuration

​Data Types

​Date Range Options

​Export Data Structure

​Usage Exports

​Column Definitions

​Additional Columns for BYOK Workspaces

​Subgroup Rows

​Column Definitions

​Additional Columns for BYOK Workspaces

​Subgroup Rows

​Additional Columns for BYOK Workspaces

​Subgroup Rows

​Column Definitions

​Column Definitions

​Additional Columns for BYOK Workspaces

​Subgroup Rows

​Actions Referenced in User Export

​Data Handling and Privacy

​Null Values

​Data Retention

Accessing Usage Exports

Export Configuration

Data Types

Date Range Options

Export Data Structure

Usage Exports

Column Definitions

Additional Columns for BYOK Workspaces

Subgroup Rows

Column Definitions

Additional Columns for BYOK Workspaces

Subgroup Rows

Additional Columns for BYOK Workspaces

Subgroup Rows

Column Definitions

Column Definitions

Additional Columns for BYOK Workspaces

Subgroup Rows

Actions Referenced in User Export

Data Handling and Privacy

Null Values

Data Retention