Skip to content
HotKVDocs

Ask the HotKV docs

Answers come only from these docs and can be wrong; check the linked pages before you rely on them.

LLMBUDGET.CONSUME

Last updated 
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)
Arity
-4 (at least 4 words, counting the command name)
Flags
write, fast
Keys
first 1, last 1, step 1
HotKV Cloud
Performance and Scale
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

Section titled “Options”
Option Effect
MODEL model Price the request from the shared price table (see LLMSTATS.PRICE). 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

Section titled “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

Section titled “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

Section titled “Compatibility”

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

See also

Section titled “See also”

LLMBUDGET.SET, LLMBUDGET.STATUS, LLMBUDGET.RESET, LLMBUDGET.DROP, LLMBUDGET.LIST, LLMSTATS.RECORD, AI features guide