Export User Usage

Export user usage data

curl --request POST \
  --url https://api.langdock.com/export/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "date": "2024-01-01T00:00:00.000Z",
    "timezone": "UTC"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999Z",
    "timezone": "UTC"
  },
  "group_by": "model"
}
'

{
  "success": true,
  "data": {
    "filePath": "agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv",
    "downloadUrl": "https://storage.example.com/signed-url",
    "dataType": "assistants",
    "recordCount": 1250,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000Z",
      "to": "2024-01-31T23:59:59.999Z"
    }
  }
}

POST

export

users

Export user usage data

curl --request POST \
  --url https://api.langdock.com/export/users \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "date": "2024-01-01T00:00:00.000Z",
    "timezone": "UTC"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999Z",
    "timezone": "UTC"
  },
  "group_by": "model"
}
'

{
  "success": true,
  "data": {
    "filePath": "agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv",
    "downloadUrl": "https://storage.example.com/signed-url",
    "dataType": "assistants",
    "recordCount": 1250,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000Z",
      "to": "2024-01-31T23:59:59.999Z"
    }
  }
}

This endpoint exports user activity data including message counts, usage patterns, and feature utilization. The available data depends on your workspace privacy settings.

Using a dedicated deployment?Replace api.langdock.com with <your-deployment>/api/public in all requests.

For details on prerequisites and rate limits, please refer to the main Usage Export API documentation.

Langdock intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

Privacy Considerations

The user export data is subject to workspace privacy settings, user-identifying data may be excluded due to privacy settings. As a consequence of this some data may be anonymized based on workspace configuration.

Data Included

By default, the user export returns one row per user for the selected period.

Column	Description
`period_start`	Start date of the report
`period_end`	End date of the report
`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
`joined_at`	Date the user joined the workspace
`department`	User department
`company_name`	User company name
`license_type`	Current 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

Because BYOK workspaces supply their own model keys, Langdock can provide token consumption and costs directly. This is not possible when obtaining your models directly through Langdock.

Grouped Export

Use group_by=model to return one row per user and model.

Authorizations

Authorization

string

header

required

API key as Bearer token. Format "Bearer YOUR_API_KEY"

Body

application/json

Request body for usage export endpoints

from

object

required

Start date and timezone for the export

Show child attributes

object

required

End date and timezone for the export

Show child attributes

group_by

enum<string>

Optional aggregation dimension.

Available options:

model

Response

Export successful

Successful response from usage export endpoints

success

boolean

required

Indicates if the export was successful

Example:

true

data

object

required

Export data information

Show child attributes

Introduction to Usage Export Export Agent Usage

⌘I

​Privacy Considerations

​Data Included

​Additional Columns for BYOK Workspaces

​Grouped Export

Authorizations

Body

Response

Privacy Considerations

Data Included

Additional Columns for BYOK Workspaces

Grouped Export