> ## Documentation Index > Fetch the complete documentation index at: https://docs.langdock.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Workspace Settings > Read workspace usage limits, plan budgets, usage requests, and agent limit behavior Read and update the workspace limits and plan budgets for mode `bring-your-own-keys`. Amounts are US dollars. The call uses the workspace API key's `BILLING_API` scope. Writes run as the key's service account owner. ## Base URL ``` https://api.langdock.com/billing/v1/bring-your-own-keys/settings ``` > [!WARNING] > > **Dedicated deployments** > > Replace `api.langdock.com` with `/api/public` in all requests. ## Prerequisites * **API key** with the `BILLING_API` scope * The key owner is a service account that has not been deleted and has an active Admin membership ## Read settings `GET /billing/v1/bring-your-own-keys/settings` returns the current settings. ```json theme={null} { "currency": "USD", "usageRequestsEnabled": true, "workspaceUsageLimit": { "type": "unlimited" }, "monthlyBudgetPerPlan": { "standard": { "type": "limited", "amount": 36 }, "power_user": { "type": "limited", "amount": 120 } }, "weeklyBudgetPerPlan": { "standard": { "type": "limited", "amount": 9 }, "power_user": { "type": "limited", "amount": 30 } }, "sessionBudgetPerPlan": { "standard": { "type": "limited", "amount": 3 }, "power_user": { "type": "limited", "amount": 10 } }, "sessionLimitsEnabled": true, "agentLimitBehavior": { "forced": "switch_model", "fallbackModelId": "44444444-4444-4444-8444-444444444444" }, "usagePeriod": { "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z" }, "usagePeriodSpend": 1290.1 } ``` `workspaceUsageLimit` caps included and extra chat and agent usage in `usagePeriod`. Personal API usage counts toward that cap, and so do Agent API calls with a workspace key when the agent budget is `always` with a limited amount. Other workspace API usage, workflow runs, and usage of the workspace backbone model do not. `usagePeriodSpend` is the usage counted toward that cap. `monthlyBudgetPerPlan` is the included allowance for **Standard** (`standard`) and **Power user** (`power_user`). Weekly and session budgets are derived and you cannot write them. The weekly amount is the monthly amount divided by 4. The session amount is the weekly amount divided by 3. An unlimited monthly budget stays unlimited on those windows. `sessionBudgetPerPlan` is `null` when session limits are off. The monthly amount sets those windows. Extra usage can start when the included weekly or session allowance is used up. It is not a promise that extra usage waits for a calendar month to end. `usageRequestsEnabled` lets members ask an admin for more usage. `agentLimitBehavior.forced` chooses what happens after a member or agent limit is reached: * `null` leaves the choice to the agent owner (**Agent owner decides**). * `switch_model` switches to the fallback model (**Switch model**). This requires a valid fallback. * `block_usage` stops the agent (**Block usage**). `fallbackModelId` is the configured fallback. `null` uses the workspace backbone model. Forcing `switch_model` still requires that resulting model to be valid. > [!NOTE] > > 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](https://docs.langdock.com/en/admin/ai-adoption-and-rollout/best-practices/api-key-best-practices.md). ## OpenAPI ````yaml GET /billing/v1/bring-your-own-keys/settings openapi: 3.0.0 info: title: Langdock API version: 3.0.0 servers: - url: https://api.langdock.com description: Production security: - bearerAuth: [] paths: /billing/v1/bring-your-own-keys/settings: get: tags: - Settings summary: Read USD workspace settings operationId: getByokBillingSettings responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/ByokSettings' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '405': $ref: '#/components/responses/MethodNotAllowed' '409': $ref: '#/components/responses/ModeMismatch' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: ByokSettings: type: object additionalProperties: false required: - currency - usageRequestsEnabled - workspaceUsageLimit - monthlyBudgetPerPlan - sessionLimitsEnabled - agentLimitBehavior - weeklyBudgetPerPlan - sessionBudgetPerPlan - usagePeriod - usagePeriodSpend properties: currency: type: string enum: - USD usageRequestsEnabled: type: boolean workspaceUsageLimit: $ref: '#/components/schemas/WorkspaceLimit' monthlyBudgetPerPlan: $ref: '#/components/schemas/ByokPlanLimits' sessionLimitsEnabled: type: boolean agentLimitBehavior: $ref: '#/components/schemas/AgentLimitBehavior' weeklyBudgetPerPlan: $ref: '#/components/schemas/ByokPlanLimits' sessionBudgetPerPlan: type: object additionalProperties: false required: - standard - power_user properties: standard: $ref: '#/components/schemas/Limit' power_user: $ref: '#/components/schemas/Limit' nullable: true usagePeriod: $ref: '#/components/schemas/Period' usagePeriodSpend: type: number minimum: 0 nullable: true description: >- USD included and extra chat/agent usage; excludes workflow, API, and backbone-model usage. Weekly budgets are monthly / 4; session budgets are weekly / 3 and null when disabled. PATCH returns null spending; GET retrieves spending. WorkspaceLimit: oneOf: - type: object additionalProperties: false required: - type - amount properties: type: type: string enum: - limited amount: type: number minimum: 0 exclusiveMinimum: true - type: object additionalProperties: false required: - type properties: type: type: string enum: - unlimited ByokPlanLimits: type: object additionalProperties: false required: - standard - power_user properties: standard: $ref: '#/components/schemas/Limit' power_user: $ref: '#/components/schemas/Limit' AgentLimitBehavior: type: object additionalProperties: false required: - forced - fallbackModelId properties: forced: type: string enum: - switch_model - block_usage - null nullable: true fallbackModelId: type: string format: uuid nullable: true description: >- Forcing switch_model requires a valid fallback model. null forced uses each agent setting. fallbackModelId is the configured override; null uses the workspace backbone fallback. Limit: oneOf: - type: object additionalProperties: false required: - type - amount properties: type: type: string enum: - limited amount: type: number minimum: 0 - type: object additionalProperties: false required: - type properties: type: type: string enum: - unlimited Period: type: object additionalProperties: false required: - start - end properties: start: type: string format: date-time end: type: string format: date-time Error: type: object additionalProperties: false required: - message - code properties: message: type: string code: type: string details: type: object additionalProperties: true description: >- Optional structured details specific to the error code, such as userIds for invalid bulk members. ModeMismatchError: type: object additionalProperties: false required: - message - code - details properties: message: type: string code: type: string enum: - BILLING_MODE_MISMATCH details: type: object additionalProperties: false required: - mode properties: mode: type: string enum: - ai-models-included - bring-your-own-keys responses: BadRequest: description: >- Invalid body/query, unknown fields, empty PATCH, invalid limit, invalid bulk member IDs, or a cursor outside this workspace (INVALID_CURSOR). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Missing Billing scope, personal key, unavailable feature, missing active service-account Admin authority, or email filter without the USER_MANAGEMENT_API scope. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: >- Resource not in this workspace, inactive/non-human user, privacy-hidden agent, usage request not found for that member, or endpoint unavailable in this mode. content: application/json: schema: $ref: '#/components/schemas/Error' MethodNotAllowed: description: Unsupported HTTP method. content: application/json: schema: $ref: '#/components/schemas/Error' ModeMismatch: description: >- Workspace mode differs from the requested mode. details.mode identifies the workspace mode. content: application/json: schema: $ref: '#/components/schemas/ModeMismatchError' TooManyRequests: description: API rate limit exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: API key as Bearer token. Format "Bearer YOUR_API_KEY" ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.