> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-ai-gateway/user-guide/teams-keys-and-budgets.md).

# Teams, keys and budgets

Who may call which model, and how much they may spend.

A **team** carries the rules: which models it may use, its budget and its limits. A **virtual key** belongs to a team and is what a person or an application sends with every call. The provider credential never leaves the gateway, so revoking a key is enough to cut someone off.

All calls below use the gateway's master key and go to the LLM gateway at `http://localhost:4000`.

{% hint style="info" %}
Next on the [roadmap](/visdom-ai-gateway/roadmap.md): teams, keys and budgets created in the Control Plane and written to the gateway, so they follow the same people and projects as the rest of Visdom. Until then, manage them here.
{% endhint %}

## Create a team with a budget

```bash
curl -s localhost:4000/team/new \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
  -d '{
        "team_alias": "payments",
        "models": ["claude-sonnet", "local-coder"],
        "max_budget": 500,
        "soft_budget": 400,
        "budget_duration": "30d",
        "rpm_limit": 600,
        "tpm_limit": 2000000
      }'
```

* `models` – the allow-list. A call for any other alias is refused with HTTP 403.
* `soft_budget` – the alert threshold; 400 of 500 is 80%.
* `max_budget` – the hard limit in USD for each `budget_duration`. Past it, calls are refused with HTTP 429 until the period resets.
* `rpm_limit`, `tpm_limit` – requests and tokens per minute for the whole team.

## Issue a key

```bash
curl -s localhost:4000/key/generate \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "team_id": "<team id>", "key_alias": "payments-ci", "max_budget": 50, "duration": "30d" }'
```

A key can have its own, smaller budget and an expiry. Give each application its own key, so its spend is visible on its own and it can be revoked alone.

## Read spend

```bash
curl -s "localhost:4000/team/info?team_id=<team id>" -H "Authorization: Bearer $LITELLM_MASTER_KEY"
```

Spend is written in batches a few seconds after each call and is also visible in the admin UI at `/ui`.

## Alerts

To receive budget alerts, set `WEBHOOK_URL` on the `llm-gateway` service and enable webhook alerting in `config.yaml`:

```yaml
general_settings:
  alerting: ["webhook"]
  alert_types: ["budget_alerts"]
```

## Revoke

```bash
curl -s localhost:4000/key/delete \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" -H 'Content-Type: application/json' \
  -d '{ "keys": ["<virtual key>"] }'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.visdom.virtuslab.com/visdom-ai-gateway/user-guide/teams-keys-and-budgets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.