Export User Usage

API endpoint to export user activity data including message counts and usage patterns (subject to privacy settings)

POST /export/users

Export user usage data

cURL

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

import requests

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

payload = {
    "from": {
        "date": "2024-01-01T00:00:00.000Z",
        "timezone": "UTC"
    },
    "to": {
        "date": "2024-01-31T23:59:59.999Z",
        "timezone": "UTC"
    },
    "group_by": "model"
}
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'},
    group_by: 'model'
  })
};

fetch('https://api.langdock.com/export/users', 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/users",
  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'
    ],
    'group_by' => 'model'
  ]),
  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/users"

	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  \"group_by\": \"model\"\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/users")
  .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  \"group_by\": \"model\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.langdock.com/export/users")

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  \"group_by\": \"model\"\n}"

response = http.request(request)
puts response.read_body

200

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

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

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

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

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

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