> ## 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.
# Export Agent Usage
> API endpoint to export agent usage data including message counts, active users, and trends
This endpoint exports agent usage data including message counts per agent, active user counts, and usage trends over time.
## Before You Start
* **Prerequisites and rate limits**: See the [Usage Export API overview](/en/developer/usage-export-api/intro-to-usage-export-api).
* **Browser requests**: Langdock intentionally blocks browser-origin requests to protect your API key. Use API keys server-side and store them securely. See [API Key Best Practices](/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices).
## Base URL
```
https://api.langdock.com/export/agents
```
**Dedicated deployments**
Replace `api.langdock.com` with `/api/public` in all requests.
The legacy path `/export/assistants` remains available and returns the same data.
## Data Included
By default, the agent export returns one row per agent 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 |
| `assistant_id` | ID of the agent |
| `assistant_name` | Name of the agent |
| `model` | Model configured on the agent; empty when unset |
| `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 agent analytics |
| `conversations` | Number of conversations from agent analytics |
| `messages_per_user` | Average messages per active user |
| `assistant_description` | Agent description; excluded when user-level data is disabled |
| `assistant_url` | Link to the agent; excluded when user-level data is disabled |
| `assistant_owner_id` | ID of the agent owner; excluded when user-level data is disabled |
| `assistant_owner_email` | Email of the agent owner; excluded when user-level data is disabled |
### 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`.
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. In grouped rows, `model` is the model that produced the usage, not the model configured on the agent. Agent-level KPI fields are omitted in grouped mode.
## OpenAPI
````yaml POST /export/agents
openapi: 3.0.0
info:
title: Langdock API
version: 3.0.0
servers:
- url: https://api.langdock.com
description: Production
security:
- bearerAuth: []
paths:
/export/agents:
post:
tags:
- Usage Export
summary: Export agent usage data
description: Export detailed usage data for all agents in the workspace
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportModelGroupByRequest'
example:
from:
date: '2024-01-01T00:00:00.000Z'
timezone: UTC
to:
date: '2024-01-31T23:59:59.999Z'
timezone: UTC
responses:
'200':
description: Export successful
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportResponse'
example:
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'
'400':
description: Bad Request - Export too large or invalid date range
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
example:
message: >-
Export too large: more than 1,000,000 usage rows for the
selected date range. Try a shorter date range and combine the
CSV files.
code: USAGE_EXPORT_TOO_LARGE
details:
usageRows: 1500000
limit: 1000000
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
example:
message: The provided API key is invalid.
'404':
description: No data found for the selected period
content:
application/json:
schema:
$ref: '#/components/schemas/UsageExportError'
example:
message: No usage data found for the selected period
code: NOT_FOUND
components:
schemas:
UsageExportModelGroupByRequest:
allOf:
- $ref: '#/components/schemas/UsageExportRequest'
- type: object
properties:
group_by:
type: string
description: Optional aggregation dimension.
enum:
- model
UsageExportResponse:
type: object
description: Successful response from usage export endpoints
properties:
success:
type: boolean
description: Indicates if the export was successful
example: true
data:
type: object
description: Export data information
properties:
filePath:
type: string
description: Path to the generated export file
example: >-
agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv
downloadUrl:
type: string
format: uri
description: Signed URL to download the export file
example: https://storage.example.com/signed-url
dataType:
type: string
description: Type of data exported
enum:
- assistants
- agents
- api_keys
- users
- projects
- models
- workflows
example: assistants
recordCount:
type: integer
description: Number of records in the export
example: 1250
dateRange:
type: object
description: Actual date range of the exported data
properties:
from:
type: string
format: date-time
description: Start date of the export
example: '2024-01-01T00:00:00.000Z'
to:
type: string
format: date-time
description: End date of the export
example: '2024-01-31T23:59:59.999Z'
required:
- from
- to
required:
- filePath
- downloadUrl
- dataType
- recordCount
- dateRange
required:
- success
- data
UsageExportError:
type: object
description: Error response from usage export endpoints
properties:
message:
type: string
description: Detailed error message
example: No usage data found for the selected period
code:
type: string
description: Machine-readable error code
example: NOT_FOUND
details:
type: object
description: >-
Additional error context. Oversized exports include the scanned row
counts and the configured row limit.
required:
- message
UsageExportRequest:
type: object
description: Request body for usage export endpoints
properties:
from:
type: object
description: Start date and timezone for the export
properties:
date:
type: string
format: date-time
description: Start date in ISO 8601 format
example: '2024-01-01T00:00:00.000Z'
timezone:
type: string
description: Timezone for the date range
example: UTC
required:
- date
- timezone
to:
type: object
description: End date and timezone for the export
properties:
date:
type: string
format: date-time
description: End date in ISO 8601 format
example: '2024-01-31T23:59:59.999Z'
timezone:
type: string
description: Timezone for the date range
example: UTC
required:
- date
- timezone
required:
- from
- to
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: API key as Bearer token. Format "Bearer YOUR_API_KEY"
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.