Export agent usage data
curl --request POST \
--url https://api.langdock.com/export/agents \
--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"
}
}
'import requests
url = "https://api.langdock.com/export/agents"
payload = {
"from": {
"date": "2024-01-01T00:00:00.000Z",
"timezone": "UTC"
},
"to": {
"date": "2024-01-31T23:59:59.999Z",
"timezone": "UTC"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
from: {date: '2024-01-01T00:00:00.000Z', timezone: 'UTC'},
to: {date: '2024-01-31T23:59:59.999Z', timezone: 'UTC'}
})
};
fetch('https://api.langdock.com/export/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.langdock.com/export/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from' => [
'date' => '2024-01-01T00:00:00.000Z',
'timezone' => 'UTC'
],
'to' => [
'date' => '2024-01-31T23:59:59.999Z',
'timezone' => 'UTC'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.langdock.com/export/agents"
payload := strings.NewReader("{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.langdock.com/export/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.langdock.com/export/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}
}{
"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
}
}{
"message": "The provided API key is invalid."
}{
"message": "No usage data found for the selected period",
"code": "NOT_FOUND"
}Usage Export API
Export Agent Usage
API endpoint to export agent usage data including message counts, active users, and trends
POST
/
export
/
agents
Export agent usage data
curl --request POST \
--url https://api.langdock.com/export/agents \
--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"
}
}
'import requests
url = "https://api.langdock.com/export/agents"
payload = {
"from": {
"date": "2024-01-01T00:00:00.000Z",
"timezone": "UTC"
},
"to": {
"date": "2024-01-31T23:59:59.999Z",
"timezone": "UTC"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
from: {date: '2024-01-01T00:00:00.000Z', timezone: 'UTC'},
to: {date: '2024-01-31T23:59:59.999Z', timezone: 'UTC'}
})
};
fetch('https://api.langdock.com/export/agents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.langdock.com/export/agents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'from' => [
'date' => '2024-01-01T00:00:00.000Z',
'timezone' => 'UTC'
],
'to' => [
'date' => '2024-01-31T23:59:59.999Z',
'timezone' => 'UTC'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.langdock.com/export/agents"
payload := strings.NewReader("{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.langdock.com/export/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.langdock.com/export/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"from\": {\n \"date\": \"2024-01-01T00:00:00.000Z\",\n \"timezone\": \"UTC\"\n },\n \"to\": {\n \"date\": \"2024-01-31T23:59:59.999Z\",\n \"timezone\": \"UTC\"\n }\n}"
response = http.request(request)
puts response.read_body{
"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"
}
}
}{
"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
}
}{
"message": "The provided API key is invalid."
}{
"message": "No usage data found for the selected period",
"code": "NOT_FOUND"
}This endpoint exports agent usage data including message counts per agent, active user counts, and usage trends over time.
The legacy path
Before You Start
- Prerequisites and rate limits: See the Usage Export API overview.
- 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.
Base URL
https://api.langdock.com/export/agents
Dedicated deploymentsReplace
api.langdock.com with <your-deployment-url>/api/public in all requests./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
Usegroup_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.Authorizations
API key as Bearer token. Format "Bearer YOUR_API_KEY"
Body
application/json
Was this page helpful?