Skip to main content
POST
/
export
/
assistants
Export assistant usage data
curl --request POST \
  --url https://api.langdock.com/export/assistants \
  --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"
  }
}
'
{
  "success": true,
  "data": {
    "filePath": "assistants-usage/workspace-id/assistants-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 agent usage data including message counts per agent, active user counts, and usage trends over time.
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.

​
Data Included

By default, the agent export returns one row per agent for the selected period.
ColumnDescription
period_startStart date of the report
period_endEnd date of the report
org_idID of the workspace
assistant_idID of the agent
assistant_nameName of the agent
messagesNumber of user messages sent to the agent
unique_usersNumber of users who messaged the agent
active_usersNumber of active users from agent analytics
conversationsNumber of conversations from agent analytics
messages_per_userAverage messages per active user
assistant_descriptionAgent description; excluded when user-level data is disabled
assistant_urlLink to the agent; excluded when user-level data is disabled
assistant_owner_idID of the agent owner; excluded when user-level data is disabled
assistant_owner_emailEmail of the agent owner; excluded when user-level data is disabled

​
Additional Columns for BYOK Workspaces

ColumnDescription
sum_prompt_tokensTotal input tokens
avg_prompt_tokensAverage input tokens per request
min_prompt_tokensMinimum input tokens per request
max_prompt_tokensMaximum input tokens per request
sum_completion_tokensTotal output tokens
avg_completion_tokensAverage output tokens per request
min_completion_tokensMinimum output tokens per request
max_completion_tokensMaximum output tokens per request
sum_cached_prompt_tokensCache-read input tokens
sum_cache_creation_tokensCache-write input tokens
sum_no_cache_tokensInput tokens that were not served from cache
Because BYOK workspaces supply their own model keys, Langdock can provide token consumption data directly. This is not possible when obtaining your models directly through Langdock.

​
Grouped Export

Use group_by=model to return one row per agent and model. Agent-level KPI fields are omitted in grouped mode.

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

​
to
object
required

End date and timezone for the export

​
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