Start with
GET /billing/v1/mode, then call only that mode’s routes. Dedicated deployments always return bring-your-own-keys, including when Langdock manages the model keys. A Cloud workspace returns ai-models-included when Langdock provides the models, and bring-your-own-keys when the workspace brings its own keys. You can grant the Billing API scope on Cloud and on Dedicated deployments. The other mode’s routes return 409.Before You Start
- API key scope:
BILLING_APIon a workspace API key. In the scope picker the scope is labeled Billing API and sits in the Billing group, after User management and before Audit log. Personal keys cannot take this scope. Existing workspace keys do not gain it on their own. - Owner: The key owner is a service account that has not been deleted and has an active Admin membership. Writes run as that service account. If that membership is gone, calls return
403withcodeBILLING_API_ADMIN_REQUIRED. - Names and emails: User objects always include
id, the plan, and limits. They includeemailandnameonly when the same key also hasUSER_MANAGEMENT_API. Filtering users byemailwithout that scope returns403withcodeUSER_MANAGEMENT_API_REQUIRED.
409 with code BILLING_MODE_MISMATCH and the workspace mode in details.mode.
Base URL
Billing mode
bring-your-own-keys uses US dollars:
standard (Standard) and power_user (Power user). There is no seats route.
ai-models-included uses euros:
business (Business) and business_max (Business Max). There is no plan-count route. Paid seats are on Get Seats.
A path that does not exist in the workspace mode, such as seats on bring-your-own-keys or plan counts on ai-models-included, returns 404.
Limits
Send and read a limit in one of these shapes. Onlylimited includes amount.
bring-your-own-keys, extra usage budgets also accept { "type": "none" }. none removes that extra allowance. Agent budgets accept none in both modes. none removes the separate agent budget.
In ai-models-included, a member’s extra usage limit also accepts { "type": "inherit" }. inherit uses the plan and group defaults. A group limit does not accept inherit or none.
A PATCH must include at least one field you can write. Fields you omit stay as they are. In bring-your-own-keys, a plan you leave out of monthlyBudgetPerPlan keeps its budget. In ai-models-included, a plan you leave out of defaultExtraUsageLimitPerPlan keeps its limit. Unknown fields are rejected.
Lists and spend
Lists default to 50 items. Setlimit from 1 to 250. Pass cursor from the previous page’s nextCursor, and keep the same filters. nextCursor is omitted on the last page. Treat the cursor as opaque.
GET returns spend when the workspace shows per user spend. When that spend is hidden, the spend field is null. User, settings, and agent writes always return null for spend, so a write that already succeeded does not fail while spend is loading. Read the resource again to get spend.
Bring your own keys
AI models included
Amounts on these routes are euros. Call them when mode discovery returnsai-models-included.
Errors
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.