Skip to main content
POST
Export user usage data
This endpoint exports user activity data including message counts, usage patterns, and feature utilization. The available data depends on your workspace privacy settings.

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

Dedicated deploymentsReplace api.langdock.com with <your-deployment-url>/api/public in all requests.

Privacy Considerations

The User-level data setting controls whether user detail columns are included in the default export. When it is disabled, the columns marked below are omitted, including name and email. Rows grouped by department or company_name still include that grouping key, and they never include user identity.

Data Included

By default, the user export returns one row per user for the selected period. An unlimited payg_limit_current, a payg_utilization_pct_current with no positive limit, and an empty payg_limit_group_name are null in the JSON response. In the CSV those cells are empty. payg_limit_current is the extra usage limit in effect when you run the export, in EUR for Langdock Cloud workspaces without BYOK and in USD for BYOK and dedicated deployments. payg_consumption_in_period is spend in the selected period, rounded to two decimal places. Without BYOK, that spend is extra usage in EUR. Spend charged to an agent’s own usage limit is left out of that figure. On BYOK and dedicated deployments it is the USD cost of every row that counts against usage limits, including spend charged to an agent’s own usage limit. payg_utilization_pct_current is that consumption divided by the current limit, rounded to four decimal places. It is a ratio, not a percentage from 0 to 100, and it can be greater than 1. It is null when the limit is unlimited, 0, or negative. A positive limit with no consumption in the period is 0. payg_limit_source is plan, user, group, or workspace. On Usage and spend they appear as Individual, Workspace, and Plan or Group followed by the plan or group name. Without BYOK, and with extra usage on, the highest applicable plan or group limit is used by default. Unlimited counts as the highest. On a tie, including two unlimited limits, a group wins over the plan, and the group whose name comes first alphabetically wins over other groups. An individual Custom or Unlimited limit overrides it, even a Custom amount of 0. payg_limit_group_name is the name of the group whose limit applies, and null otherwise. There is one consumption figure per user, not one per group. When extra usage is off in Langdock Cloud workspaces without BYOK, payg_limit_current is 0 and payg_limit_source is workspace. On BYOK and dedicated deployments the limit comes only from the individual extra usage setting. With neither Custom nor Unlimited selected, the amount is 0 and the source is user.

Additional Columns for BYOK Workspaces

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. payg_consumption_in_period and payg_utilization_pct_current are for that model only. payg_limit_current, payg_limit_source, and payg_limit_group_name repeat the user’s current limit on every model row, so do not add the limit across those rows. Use group_by=department or group_by=company_name to return one row per department or company name. Langdock records each user’s department and company from their profile when they sign in to the workspace. Each usage event uses the latest value recorded at or before that event, so a profile change, for example through SCIM, applies from the user’s next sign-in. A later change keeps the earlier and later values in separate rows. These rows omit user identity, including when User-level data is on. A recorded empty department or company is returned as No department or No company, with attribution_status attributed, unless it is combined as described below. Usage from before the first recorded value has an empty grouping key and attribution_status pre_cutoff. This includes recent usage from users who have not signed in since recording started. Without breakdown, grouped rows include period_start, period_end, org_id, the grouping key, attribution_status, messages_total, messages_chat, messages_assistants, assistants_messaged, messages_projects, and active_users. active_users counts distinct users with a prompt in the period, including API usage. Cloud workspaces that are not BYOK also include payg_consumption_in_period, including when User-level data is off. BYOK workspaces and dedicated deployments include total_input_tokens, total_output_tokens, cached_prompt_tokens, cache_creation_tokens, no_cache_tokens, and total_cost_usd instead. When User-level data is off, an attributed department or company with fewer than 5 active users is combined into Combined departments or Combined companies. Rows with pre_cutoff stay separate. Pass breakdown=agent or breakdown=model with group_by=department or group_by=company_name to split each group by agent or model. Those rows use messages and active_users instead of the message columns above, plus agent_id and agent_name or model, and the same cost columns. Agent rows cover agents only, not chat or projects, and model rows also count image generation, so messages does not add up to messages_total. When User-level data is off, an agent or model with fewer than 5 active users in that group is merged into Combined agents or Combined models. The combined agent row has an empty agent_id.

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. department and company_name group usage without user identity.

Available options:
model,
department,
company_name
breakdown
enum<string>

Optional split of a department or company group by agent or model. Valid only when group_by is department or company_name.

Available options:
agent,
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