# LLMBUDGET.CONSUME

> Charge tokens and cost to an LLM budget, and find out whether the request is allowed.

URL: https://docs.hotkv.com/commands/llmbudget-consume/

```
LLMBUDGET.CONSUME name tokens cost_usd [MODEL model] [INPUT n] [OUTPUT n] [CACHEREAD n] [CACHEWRITE5M n] [CACHEWRITE1H n]
```

- Group: LLM usage and budgets
- Complexity: O(1)
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the llm-budget license feature

LLM budgets put a hard cap on the tokens and dollars a named budget (for example one per tenant) can spend in a time window, so you can refuse a request before you pay the model provider for it. `LLMBUDGET.CONSUME` adds a request's usage to budget `name` if it
fits. If adding it would take the tokens or the cost over their limit in the
current window, nothing is added and the request is rejected.

Without `MODEL`, the positional `tokens` (a non-negative integer) and
`cost_usd` (a non-negative number) are charged as given.

## Options

| Option | Effect |
| --- | --- |
| `MODEL model` | Price the request from the shared price table (see [LLMSTATS.PRICE](https://docs.hotkv.com/commands/llmstats-price/index.md)). The positional `tokens` and `cost_usd` are then ignored (pass `0`): the token charge is the sum of the counts below and the cost comes from the model's price. An unpriced model is charged its tokens but `$0`, and increments `unpriced_requests`. |
| `INPUT n` | Uncached input tokens. |
| `OUTPUT n` | Output tokens. |
| `CACHEREAD n` | Provider cache-read tokens. |
| `CACHEWRITE5M n` | Tokens written to a 5-minute provider cache. |
| `CACHEWRITE1H n` | Tokens written to a 1-hour provider cache. |

Options follow `cost_usd` in name and value pairs, in any order. Token counts
need `MODEL`.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Allowed and charged | Integer `1` | Same |
| Rejected (over a limit), or no such budget | Integer `0` | Same |

Errors:

- `ERR invalid argument` if `tokens` is not a non-negative integer or `cost_usd` is negative or not a number.
- `ERR usage token counts (INPUT, OUTPUT, CACHEREAD, CACHEWRITE5M, CACHEWRITE1H) need MODEL` if you pass a token count without `MODEL`.
- `ERR invalid INPUT` (or `OUTPUT`, `CACHEREAD`, `CACHEWRITE5M`, `CACHEWRITE1H`) if a count is not a non-negative integer.
- `ERR syntax error` if an option has no value.
- `ERR unknown option` for any other option name.
- `ERR wrong number of arguments for 'llmbudget.consume' command` if the argument count is wrong.
- `NOLICENSE llm-budget requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `llm-budget` feature.

## Examples

```
127.0.0.1:6379> LLMBUDGET.SET tenant_acme 0 5.00 3600
OK
127.0.0.1:6379> LLMBUDGET.CONSUME tenant_acme 0 0 MODEL claude-sonnet-5 INPUT 100000 OUTPUT 2000
(integer) 1
127.0.0.1:6379> LLMBUDGET.CONSUME tenant_acme 0 4.90
(integer) 0
```

The second call would take the hour's spend from $0.22 to $5.12, over the
$5 cap, so it is rejected and not charged.

## Compatibility

HotKV-only command. Redis and Valkey have no equivalent.

## See also

[LLMBUDGET.SET](https://docs.hotkv.com/commands/llmbudget-set/index.md), [LLMBUDGET.STATUS](https://docs.hotkv.com/commands/llmbudget-status/index.md), [LLMBUDGET.RESET](https://docs.hotkv.com/commands/llmbudget-reset/index.md), [LLMBUDGET.DROP](https://docs.hotkv.com/commands/llmbudget-drop/index.md), [LLMBUDGET.LIST](https://docs.hotkv.com/commands/llmbudget-list/index.md), [LLMSTATS.RECORD](https://docs.hotkv.com/commands/llmstats-record/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)