# Change a workspace's budget

> Change a workspace's budget.

<div class="g1t-endpoint"><span class="g1t-method" data-method="put">PUT</span><code>/workspaces/{workspace}/budget</code></div>

Give only what you change; the rest stays as it is. `amount_micros` is the monthly spend limit, up to `max_amount_micros`, or null for the automatic one. `alerts` is some of 50, 75, 90 and 100, in percent of the limit. `pause_at_limit` false makes the limit alert only, without pausing usage; g1t's own ceiling still applies. `webhook` is an https:// address sent a JSON POST for each alert, or null for none. Owners only, as a person: signed in or with a personal access token. A workspace's own token and g1t's agents can read the budget but never change it. Returns the budget.

Fields left out keep their value. A limit above `max_amount_micros` is refused with `invalid`. Called by anyone but an owner signed in as a person, or by a workspace's own token or one of g1t's agents, it is refused with `forbidden`. Each alert is sent once a month, to the owners by email and, with `webhook`, as a JSON POST.

- **Authentication:** Required. Send an [access token](/reference/api/#authentication) as `Authorization: Bearer`.
- **MCP tool:** [`billing`](/reference/mcp/#billing) with `action` `set_budget`, and the same inputs
- **Scope:** An access token needs [`billing:write`](/guides/authentication/#scopes).

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `workspace` | string | Yes | The workspace's slug, e.g. "flagon-io". |

## Body parameters

Send a JSON object. Names are `snake_case`, as in responses; the `camelCase` spelling is accepted too.

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `amount_micros` | integer or null | No | The monthly spend limit, in millionths of a dollar: 500000000 is $500. Null for the automatic limit. Left out: unchanged. |
| `alerts` | array of integers | No | When to alert, in percent of the limit: some of 50, 75, 90 and 100. Replaces the whole list. Left out: unchanged. One of `50`, `75`, `90`, `100`. |
| `pause_at_limit` | boolean | No | Pause usage at the limit (the default), or with false, only alert. Left out: unchanged. |
| `webhook` | string or null | No | An https:// address sent a JSON POST for each alert, or null for none. Left out: unchanged. |

## Example request

```sh
curl -X PUT https://api.g1t.sh/workspaces/flagon-io/budget \
  -H "Authorization: Bearer $G1T_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_micros": 500000000,
    "alerts": [
      50,
      75,
      90,
      100
    ],
    "webhook": "https://ops.example.com/g1t/budget"
  }'
```

## Example response

A successful request answers `200` with:

```json
{
  "workspace": "flagon-io",
  "amount_micros": 500000000,
  "automatic": false,
  "spent_micros": 132450000,
  "max_amount_micros": 2000000000,
  "alerts": [
    50,
    75,
    90,
    100
  ],
  "pause_at_limit": true,
  "webhook": "https://ops.example.com/g1t/budget",
  "state": "ok",
  "message": null
}
```

## Errors

A failed request answers with one of these statuses and a body like `{"error": {"code": "not_found", "message": "Repository not found."}}`. See [errors](/reference/api/#errors).

| Status | Code | When |
| --- | --- | --- |
| 401 | `unauthenticated` | A token is required, or the one sent is not valid. |
| 403 | `forbidden` | The token is valid but not allowed to do this, such as a member-only change or an agent token outside its repository. |
| 404 | `not_found` | It does not exist, or you cannot see it. |
| 409 | `conflict` | The request conflicts with the current state. |
| 422 | `invalid` | The input is not valid. `message` says which field and why. |