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

<Info>
  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.
</Info>

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

<Steps>
  <Step title="Open Analytics">
    Go to your [workspace analytics page](https://app.langdock.com/settings/workspace/analytics) in workspace settings.
  </Step>

  <Step title="Click Export">
    Select the **Export** button located in the top right corner
  </Step>

  <Step title="Configure Export">
    Choose your data type and date range in the export dialog
  </Step>

  <Step title="Generate CSV">
    Click **Generate CSV** to create and download your export file
  </Step>
</Steps>

## 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 and can scan up to 1,000,000 usage rows per export.

If an export exceeds the row limit, choose a shorter date range and combine the CSV files.

## Export Data Structure

Each export generates a CSV file with one row per entity for the selected time period.

<Info>
  Some columns are only available for workspaces using [Bring Your Own Key (BYOK)](/en/admin/byok/byok). These are marked as **BYOK workspaces only**.
</Info>

## Usage Exports

<Tabs>
  <Tab title="Users">
    The Users export provides individual user activity across the selected period.

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

    ### 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 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 |

    ### 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`.

    ***
  </Tab>

  <Tab title="Agents">
    The Agents export shows usage statistics for each agent.

    <Warning>
      For workspaces with user-level data disabled, certain identifying columns (like user email and name) are excluded from exports to maintain privacy compliance.
    </Warning>

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

    ***
  </Tab>

  <Tab title="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.

    ***
  </Tab>

  <Tab title="Projects">
    The Projects export shows usage data for collaborative projects in your workspace.

    <Warning>
      For workspaces with user-level data disabled, certain identifying columns (like user email and name) are excluded from exports to maintain privacy compliance.
    </Warning>

    ### 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 |
  </Tab>

  <Tab title="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

    ***
  </Tab>

  <Tab title="Workflows">
    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.

    <Warning>
      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.
    </Warning>

    ### 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 |

    ***
  </Tab>
</Tabs>

## Actions Referenced in User Export

The following actions may appear in the `action_to_messages` column of the Users export:

<Accordion title="Canvas">
  Used to edit documents and code in a structured interface. Messages represent user prompts that trigger Canvas interactions (creation, querying, deletion).
</Accordion>

<Accordion title="Web Search">
  Used to search external web sources for real-time information. Messages represent user prompts that trigger web search functionality.
</Accordion>

<Accordion title="File Analysis">
  Used to analyze uploaded documents, spreadsheets, and other file types. Messages represent user prompts that trigger file processing and analysis.
</Accordion>

<Accordion title="Code Execution">
  Used to run and test code in various programming languages. Messages represent user prompts that trigger code execution requests.
</Accordion>

<Accordion title="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.
</Accordion>

## 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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.