Usage Exports

Usage exports are available to workspace administrators and provide up to 12 months of historical data across users, agents, API keys, projects, models, and workflows.

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. The button shows Preparing…. You can close the dialog.

Download the file

When the export is ready, you get a Usage export ready inbox notification. On Analytics, Recent exports lists Queued, Preparing, Ready, and Failed. Click Download when the status is Ready.

Only one Analytics export can run at a time in a workspace. If you click Generate CSV while another export is queued or preparing, you see An export is already running. Wait for it to finish or check Recent exports.

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, including personal API keys
Projects - Project-level usage data
Models - Model usage statistics, request counts, and BYOK token consumption data
Workflows - Workflow cost, run counts, and monthly cap utilization

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. In Analytics, each export can include up to 1,000,000 CSV rows and must finish within 15 minutes. If an export has too many rows or takes too long, choose a shorter date range and combine the CSV files. The Usage Export API can scan up to 1,000,000 usage rows per request.

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

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. API rows grouped by department or company name still include that grouping key.

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; empty when unlimited; included only when User-level data is enabled
`payg_consumption_in_period`	Spend in the selected period; included only when User-level data is enabled
`payg_utilization_pct_current`	`payg_consumption_in_period / payg_limit_current`; empty when the limit is unlimited, 0, or negative; included only when User-level data is enabled
`payg_limit_source`	`plan`, `user`, `group`, or `workspace`; included only when User-level data is enabled
`payg_limit_group_name`	Group name when the source is `group`; otherwise empty; 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 in chat without agents
`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

payg_limit_current is the extra usage limit in effect when you run the export, in EUR for Langdock Cloud workspaces without BYOK and in USD for BYOK and dedicated deployments. An unlimited limit is an empty cell. payg_consumption_in_period is spend in the selected period, rounded to two decimal places. Without BYOK, that spend is extra usage in EUR. Spend charged to an agent’s own usage limit is left out of that figure. On BYOK and dedicated deployments it is the USD cost of every row that counts against usage limits, including spend charged to an agent’s own usage limit.payg_utilization_pct_current is that consumption divided by the current limit, rounded to four decimal places. It is a ratio, not a percentage from 0 to 100, and it can be greater than 1. The cell is empty when the limit is unlimited, 0, or negative. A positive limit with no consumption in the period is 0.payg_limit_source is plan, user, group, or workspace. On Usage and spend they appear as Individual, Workspace, and Plan or Group followed by the plan or group name. Without BYOK, and with extra usage on, the highest applicable plan or group limit is used by default. Unlimited counts as the highest. On a tie, including two unlimited limits, a group wins over the plan, and the group whose name comes first alphabetically wins over other groups. An individual Custom or Unlimited limit overrides it, even a Custom amount of 0. payg_limit_group_name is the name of the group whose limit applies, and empty otherwise. There is one consumption figure per user, not one per group.When extra usage is off in Langdock Cloud workspaces without BYOK, payg_limit_current is 0 and payg_limit_source is workspace. On BYOK and dedicated deployments the limit comes only from the individual extra usage setting. With neither Custom nor Unlimited selected, the amount is 0 and the source is user.

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. payg_consumption_in_period and payg_utilization_pct_current are for that model only. payg_limit_current, payg_limit_source, and payg_limit_group_name repeat the user’s current limit on every model row, so do not add the limit across those rows.The export dialog offers No grouping and Model only. Group by department or company name with the Usage Export API. Each usage event uses the department or company recorded at the user’s latest workspace sign-in at or before that event.

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
`model`	Model configured on the agent; empty when unset
`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
`cache_hit_rate`	Cached share of input tokens

cache_hit_rate is sum_cached_prompt_tokens / sum_prompt_tokens as a four-decimal ratio from 0 to 1, not a percent. It is 0 when there is input and no cache reads. It is blank when total input is 0. If cached tokens exceed total input, the value is capped at 1.0000.

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, model is the model used, not the model configured on the agent. 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

The Workflows export shows cost, run counts, and monthly cap utilization for each workflow that had runs or cost in the selected period. Template workflows are excluded. The export dialog does not offer Subgroup rows for this type.

The User-level data setting controls whether owner columns are included. When disabled, workflow_owner_id and workflow_owner_email are omitted, and owner-only private workflows are excluded.

Column Definitions

Column	Description
`period_start`	Start date of the report
`period_end`	End date of the report
`org_id`	ID of the workspace
`workflow_id`	ID of the workflow
`workflow_name`	Name of the workflow
`status`	`ACTIVE`, `INACTIVE`, or `NOT_DEPLOYED`
`runs`	Number of workflow runs in the selected period
`total_cost_usd`	Cost in USD for the selected period
`monthly_limit_usd`	Current monthly USD cap for the workflow; `null` when no cap is set
`current_month_cost_usd`	Cost in USD for the current calendar month
`monthly_utilization_pct_current`	`current_month_cost_usd / monthly_limit_usd`; `null` when no cap is set
`workflow_owner_id`	ID of the workflow owner; included only when User-level data is enabled
`workflow_owner_email`	Email of the workflow owner; included only when User-level data is enabled

monthly_limit_usd, current_month_cost_usd, and monthly_utilization_pct_current use the workflow monthly USD cap and current calendar-month spend. They are not the extra-usage fields from the Users export.

Additional Columns for BYOK Workspaces

Column	Description
`sum_input_tokens`	Total input tokens
`sum_cached_input_tokens`	Cache-read input tokens
`sum_cache_creation_tokens`	Cache-write input tokens
`sum_output_tokens`	Total output tokens

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, departments, and other attributes show current values at the time of export. Department and company grouping on the Usage Export API uses the value recorded at the user’s latest sign-in at or before each usage event.

Workspace

Manage Agents

Manage Workflows

Desktop app

Manage Integrations

Manage Usage

Bring your own Keys (BYOK)

Governance

Compliance & Governance

AI Adoption & Rollout

Security

Billing

Usage Exports

Accessing Usage Exports

Export Configuration

Data Types

Date Range Options

Export Limits

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

Column Definitions

Additional Columns for BYOK Workspaces

Actions Referenced in User Export

Data Handling and Privacy

Null Values

Data Retention

​Accessing Usage Exports

​Export Configuration

​Data Types

​Date Range Options

​Export Limits

​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

​Column Definitions

​Additional Columns for BYOK Workspaces

​Actions Referenced in User Export

​Data Handling and Privacy

​Null Values

​Data Retention

Accessing Usage Exports

Export Configuration

Data Types

Date Range Options

Export Limits

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

Column Definitions

Additional Columns for BYOK Workspaces

Actions Referenced in User Export

Data Handling and Privacy

Null Values

Data Retention