> ## 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 Included Agent Budget

> Set an agent's monthly euro budget and when that budget applies

Read and update monthly agent budgets in euros. Use the `ai-models-included` 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.

> [!NOTE]
>
> Call these routes when `GET /billing/v1/mode` returns `ai-models-included`. Dedicated deployments always return `bring-your-own-keys`, including when Langdock manages the model keys. The other mode returns `409` with `code` `BILLING_MODE_MISMATCH`.

## Base URL

```
https://api.langdock.com/billing/v1/ai-models-included/agents/{agentId}
```

## 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/ai-models-included/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 in euros:

* `{ "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.

The budget is enforced only while extra usage is on. While extra usage is off, the stored budget is kept but not applied, and spend stays at zero. An active agent budget still follows the workspace extra usage cap from [Get Included Workspace Settings](https://docs.langdock.com/en/developer/billing-api/get-included-settings.md). Removing a budget does not turn that cap 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).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.