> Fetch the index of every Tonbo docs page as Markdown at https://tonbo.dev/llms.txt

# Give an Agent a budget

Last updated 12 November 2026

Put an Agent under a monthly spend limit for the Machines it creates, and give the program that runs as it a key. Owners and admins set budgets. The steps below create an Agent named `coder` with a limit of $50; what a budget counts and how it stops spending are on [Budgets](https://tonbo.dev/docs/platform/budgets.md).

## Create the Agent, its budget and its key {#create}

In the console, add the Agent on **Members** (see [Add an Agent](https://tonbo.dev/docs/platform/agents.md#add-agent)), then open **Usage & billing**, choose **Set budget** and pick the Agent. With the CLI or the API, you can cover only yourself and Agents you created:

**CLI**

```shell
tonbo agent create coder
tonbo budget add coder --limit 50 --member coder
tonbo api-key create coder --member coder
```

**API**

```shell
export AGENT=$(curl -sS https://api.tonbo.dev/v1/agents \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"coder"}' | jq -r .data.subject)

curl -sS https://api.tonbo.dev/v1/budgets \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"scope":"principals","name":"coder","limit_micros":50000000,"principals":["'"$AGENT"'"]}'

curl -sS https://api.tonbo.dev/v1/api-keys \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"coder","member":"'"$AGENT"'"}'
```

The key’s secret is in its answer only. Leave the key unnarrowed: a key narrowed to databases or streams neither manages nor calls Machines (see [What its budget limits](https://tonbo.dev/docs/platform/agents.md#agent-budget)).

## See what it has used {#watch}

**CLI**

```shell
tonbo budget show coder
```

**API**

```shell
curl -sS https://api.tonbo.dev/v1/budgets \
  -H "Authorization: Bearer $TONBO_API_KEY" | jq '.data[] | select(.name == "coder")'
```

It shows the limit, what was charged and committed this month, whom it covers, its stage and when it resets: at 00:00 UTC on the 1st.

## Change the limit {#change}

To lower it, or to add Agents you created, use the CLI or the API. The API sends the ETag a read of the budget answered:

**CLI**

```shell
tonbo budget set coder --limit 25
```

**API**

```shell
ETAG=$(curl -sS -o /dev/null -D - https://api.tonbo.dev/v1/budgets/<budget id> -H "Authorization: Bearer $TONBO_API_KEY" \
  | awk 'tolower($1) == "etag:" {sub(/\r$/, "", $2); print $2}')

curl -sS -X PATCH https://api.tonbo.dev/v1/budgets/<budget id> \
  -H "Authorization: Bearer $TONBO_API_KEY" \
  -H "If-Match: $ETAG" \
  -H "Content-Type: application/json" \
  -d '{"limit_micros":25000000}'
```

Raising a limit, renaming a budget and removing a member from it are done in the console only, on the budget’s page: the CLI prints that page and opens it, and the API refuses with `403` `budget_raise_in_console` and the page’s link. A lower limit takes effect at the next wake, the next create or the month’s reset (see [Who sets and changes a budget](https://tonbo.dev/docs/platform/budgets.md#who-changes)).
