Export Agent Usage

API endpoint to export agent usage data including message counts, active users, and trends

POST /export/assistants

Export assistant usage data

cURL

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"
  }
}
'

import requests

url = "https://api.langdock.com/export/assistants"

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/assistants', 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/assistants",
  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/assistants"

	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/assistants")
  .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/assistants")

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

200

{
  "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"
    }
  }
}

{
  "error": "Export too large",
  "message": "Export too large: 1500000 rows exceeds limit of 1000000. Please narrow the date range."
}

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

{
  "error": "No data found",
  "message": "No usage data found for the selected period"
}

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.

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

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

Show child attributes

to · object · required

End date and timezone for the export

Show child attributes

group_by · enum<string>

Optional aggregation dimension.

Available options: model

Response

200

application/json

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