> ## 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. # Update Agent Budget > Set an agent's monthly budget and when that budget applies Read and update monthly agent budgets in US dollars. Use the `bring-your-own-keys` prefix for this workspace mode. The calls use 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/agents/{agentId} ``` > [!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 ## Update a budget `PATCH /agents/{agentId}` accepts `budget`, `budgetMode`, or both. Send at least one. ```bash theme={null} curl -X PATCH https://api.langdock.com/billing/v1/bring-your-own-keys/agents/33333333-3333-4333-8333-333333333333 \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"budget":{"type":"limited","amount":40},"budgetMode":"always"}' ``` `budget` is a monthly amount: * `{ "type": "limited", "amount": 40 }` sets a cap. The amount must be greater than zero. * `{ "type": "unlimited" }` keeps a separate budget with no numeric cap. Spend can still be reported. This is different from `none`. * `{ "type": "none" }` removes the separate agent budget. The agent then follows workspace and member limits. `budgetMode` chooses when that budget is used: * `always` (**Always**) counts usage against the agent budget immediately, including API calls, and does not consume the member's allowance. * `on_limit_hit` (**After user limits**) counts usage against the member's limits first. After the member reaches a personal limit, usage counts against the agent budget. An active agent budget still follows the workspace limit and the workspace agent limit behavior from [Billing Workspace Settings](https://docs.langdock.com/en/developer/billing-api/get-settings.md). Removing a budget does not turn those controls off. The response is the agent object with `budgetPeriodSpend` set to `null`. Read the agent again to get spend. > [!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 PATCH /billing/v1/bring-your-own-keys/agents/{agentId} 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/agents/{agentId}: parameters: - $ref: '#/components/parameters/AgentId' patch: tags: - Agents summary: Update an agent budget in USD description: >- At least one field is required. none removes the separate agent budget; unlimited keeps it active without a numeric cap. Private agents return 404 when user-level usage is hidden. budgetPeriodSpend is always null in the mutation response. operationId: patchByokBillingAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentPatch' responses: '200': description: Updated resource. Spending is null; GET retrieves spending. content: application/json: schema: $ref: '#/components/schemas/Agent' '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: parameters: AgentId: in: path name: agentId required: true schema: type: string format: uuid schemas: AgentPatch: type: object additionalProperties: false properties: budget: $ref: '#/components/schemas/AgentBudget' budgetMode: type: string enum: - always - on_limit_hit minProperties: 1 Agent: type: object additionalProperties: false required: - id - name - budget - budgetMode - budgetPeriodSpend properties: id: type: string format: uuid name: type: string nullable: true budget: $ref: '#/components/schemas/AgentBudget' budgetMode: type: string enum: - always - on_limit_hit budgetPeriodSpend: type: number minimum: 0 nullable: true description: >- Monthly budget in mode currency, subject to workspace enforcement. always uses agent allowance; on_limit_hit uses it after the member allowance. Spend is null when user-level usage is hidden and always null on PATCH. AgentBudget: 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 - type: object additionalProperties: false required: - type properties: type: type: string enum: - none description: >- Monthly budget in the mode currency. none follows workspace/member limits; unlimited keeps a separate budget without a numeric cap. 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.