# Agent Budget
Cap business-agent usage so costs and conversation length stay predictable.
A budget caps agent usage within a rolling time window. Use these endpoints to read the budgets configured for an agent and to replace them.
Each budget is a combination of three things:
- `unit_type` — what is being measured: token usage across the Business Manager or AI agent turns within each conversation.
- `time_window` — the period the usage is totalled over: one day, seven days, fourteen days, or thirty days. Windows roll rather than resetting on a fixed calendar boundary, and are measured in the timezone of the WhatsApp Business Account.
- `max_budget` — the maximum allowed usage in that window.
You can configure several budgets at once — for example a one-day token cap alongside a one-day AI-turn cap and longer rolling caps. A given `unit_type`, `time_window` and campaign period may only appear once; a request containing two budgets that match on all three is rejected. To raise or lower an existing cap, edit that budget rather than adding a second one for the same window and period.
A budget can also be limited to a campaign by setting `start_date` and `end_date`. It then counts only usage from `start_date` onward, so spend from before the campaign began does not count against it, and it stops applying after `end_date`. Because usage is only totalled over `time_window`, the period between the two dates must be no longer than that window, and a longer period is rejected. Since the campaign period is part of what makes a budget unique, the same `unit_type` and `time_window` can be used for consecutive campaigns.
When more than one budget is configured, whichever is reached first takes effect. Once a budget is reached the agent completes the turn it is already working on, then stops replying to new messages and hands the conversation to a human using the routing the agent is already set up with. Replies resume once the time window rolls over.
An agent with no budgets configured has unlimited usage.
Reading and replacing budgets have call limits of their own, counted for each app and `entity_id` pair: 1,000 reads and 1,000 replacements per hour. Once a limit is exhausted, further requests return `429` until it resets. This is a limit on calls to these endpoints and is unrelated to the spend budgets they configure.
## Base URL
| URL | Description |
|-----|-------------|
| https://api.facebook.com/{entity_id}/agent_budget | |
## Authorization
This API requires:
any of the following
- Capability: bizai_wa_enterprise_api_3p_access
- Permission: business_management
## APIs
| Method | Endpoint |
|--------|----------|
| GET | [/](#get) |
| POST | [/](#post) |
<jumplink id="get"></jumplink>
## GET /
Get the agent budgets
Retrieve every budget currently configured for the agent. An empty `budgets` array means no cap is set and usage is unlimited.
### Header Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| X-API-Version | "2.0.0" | | |
### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| entity_id | integer | ✓ | The Business Manager ID that owns the agent — not the WhatsApp Business Phone Number ID used by the other agent endpoints. |
### Responses
**200**
The budgets currently configured for the agent.
**Content Type**: `application/json`
**Schema**: [AgentBudgetResponse](#agentbudgetresponse)
**400**
Bad request
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**404**
Not found
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**401**
Unauthorized
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**403**
Forbidden
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**429**
Too many requests
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**500**
Server error
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
<jumplink id="post"></jumplink>
## POST /
Replace the agent budgets
Replace the full set of budgets for the agent. The request describes the complete desired state, so any budget you leave out is removed, and an empty `budgets` array clears every budget and returns the agent to unlimited usage.
To change an existing budget, pass back the `budget_id` that was returned for it; the budget is updated in place and keeps its id. Omit `budget_id` to add a new budget and have an id assigned.
### Header Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| X-API-Version | "2.0.0" | | |
### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| entity_id | integer | ✓ | The Business Manager ID that owns the agent — not the WhatsApp Business Phone Number ID used by the other agent endpoints. |
### Request Body (Required)
**Content Type**: `application/json`
**Schema**: [AgentBudgetRequest](#agentbudgetrequest)
### Responses
**200**
The budgets configured for the agent after the update.
**Content Type**: `application/json`
**Schema**: [AgentBudgetResponse](#agentbudgetresponse)
**400**
Bad request
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**404**
Not found
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**401**
Unauthorized
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**403**
Forbidden
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**429**
Too many requests
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
**500**
Server error
**Content Type**: `application/json`
**Schema**: [StandardError](#standarderror)
# Components
## Schemas
<jumplink id="agentbudgetresponse"></jumplink>
### AgentBudgetResponse
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| budgets | array of [Budgets](#object-budgets-1) | ✓ | The budgets configured for the agent. When more than one is set, whichever is reached first takes effect. An empty array means no cap is set and usage is unlimited. |
<jumplink id="standarderror"></jumplink>
### StandardError
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| detail | string | ✓ | |
| status | integer | | |
| title | string | ✓ | |
| type | string | | |
<jumplink id="agentbudgetrequest"></jumplink>
### AgentBudgetRequest
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| budgets | array of [Budgets](#object-budgets-2) | ✓ | The complete set of budgets for the agent. This replaces any budgets already configured, so any you leave out are removed, and an empty array clears them all and returns the agent to unlimited usage. Token budgets apply across the Business Manager; AI-turn budgets apply to each conversation. A given unit type, time window and campaign period may only appear once, so the same unit type and time window can be used more than once as long as each entry covers a different campaign period. |
## Inline Object Definitions
<jumplink id="object-budgets-1"></jumplink>
### Budgets
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| budget_id | string | ✓ | Stable identifier for this budget. Pass it back on a subsequent set request to edit or preserve this budget. |
| unit_type | One of "token", "ai_turn" | ✓ | What the budget measures: token usage or AI agent turns. |
| time_window | One of "one_day", "seven_days", "fourteen_days", "thirty_days" | ✓ | The rolling period usage is totalled over, measured in the timezone of the WhatsApp Business Account. |
| max_budget | integer | ✓ | The maximum allowed usage, in the given unit, within the time window. |
| start_date | string | | The first day this budget counts usage from, as a date in YYYY-MM-DD format, measured in the timezone of the WhatsApp Business Account. Absent when the budget caps the rolling time window rather than a campaign. |
| end_date | string | | The last day this budget applies, as a date in YYYY-MM-DD format and in the same timezone as start_date. Outside start_date to end_date the budget does not apply at all. Absent when the budget has no campaign. |
<jumplink id="object-budgets-2"></jumplink>
### Budgets
| Property | Type | Required | Description |
|----------|------|----------|-------------|
| budget_id | string | | Stable identifier of the budget. For an existing budget, pass the id the server returned when it was created to edit or preserve it. For a new budget, leave it empty; the server assigns one. |
| unit_type | One of "token", "ai_turn" | ✓ | What the budget measures: token usage or AI agent turns. |
| time_window | One of "one_day", "seven_days", "fourteen_days", "thirty_days" | ✓ | The rolling period usage is totalled over, measured in the timezone of the WhatsApp Business Account. |
| max_budget | integer [min: 1] | ✓ | The maximum allowed usage, in the given unit, within the time window. Must be a positive whole number. |
| start_date | string | | The first day this budget counts usage from, as a date in YYYY-MM-DD format, measured in the timezone of the WhatsApp Business Account. Use it to cap a campaign without counting usage from before the campaign began. Setting it requires end_date, and the period from start_date to end_date must be no longer than time_window, otherwise the request is rejected. Omit both dates for a budget that simply caps the rolling time window. |
| end_date | string | | The last day this budget applies, as a date in YYYY-MM-DD format and in the same timezone as start_date. Outside start_date to end_date the budget does not apply at all, so a finished campaign stops capping usage rather than capping a shrinking part of itself. Required when start_date is set, and must not be earlier than start_date. May also be sent on its own, without start_date, for a budget that keeps capping the rolling time window until this day and then stops applying. |
## Authentication
| Method | How to send it |
|--------|----------------|
| Authorization header | `Authorization: Bearer {access-token}` |
### Global Authentication Requirements
All endpoints require: `Authorization: Bearer {access-token}`