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.

To export from the UI, navigate to your workspace analytics page and click the Export button in the top right corner.

1. Open Analytics

   Go to your workspace analytics page in workspace settings.

2. Click Export

   Select the Export button located in the top right corner

3. Configure Export

   Choose your data type and date range in the export dialog

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

Export Limits

Usage exports include up to 12 months of historical data and can scan up to 1,000,000 usage rows per export.

If a custom date range exceeds the row limit, 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). These are marked as BYOK workspaces only.

Usage Exports

Users

The Users export provides individual user activity across the selected period.

The User-level data setting controls whether user detail columns are included. When disabled, the columns marked below are omitted, including name and email.

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; included only when User-level data is enabled
name	Name of the user; included only when User-level data is enabled
email	Email of the user; included only when User-level data is enabled
role	User role at the time of export; included only when User-level data is enabled
joined_at	Date the user joined the workspace; included only when User-level data is enabled
department	User department; included only when User-level data is enabled
company_name	User company name; included only when User-level data is enabled
license_type	Current user license tier; included only when User-level data is enabled
payg_limit_current	Current extra-usage limit; included only when User-level data is enabled
payg_consumption_in_period	Extra-usage consumption in the selected period; included only when User-level data is enabled
payg_utilization_pct_current	payg_consumption_in_period / payg_limit_current; included only when User-level data is enabled
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.

---

Agents

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.

---

API Keys

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.

---

Projects

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

Models

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