# LLMSTATS.RECORD

> Record the tokens, cost and latency of one LLM request in a usage stats bucket.

URL: https://docs.hotkv.com/commands/llmstats-record/

```
LLMSTATS.RECORD name input_tokens output_tokens cached_tokens cost_usd latency_ms [ERROR 0 | 1] [MODEL model] [CACHEWRITE5M n] [CACHEWRITE1H n]
```

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

LLM usage stats keep running totals of the requests, tokens, cost and latency of your model calls in named buckets, for example one per tenant or per model. `LLMSTATS.RECORD` adds one request to bucket `name`, creating the
bucket if it does not exist.

The positional arguments are:

- `input_tokens`: uncached input tokens.
- `output_tokens`: output tokens.
- `cached_tokens`: tokens read from the provider's prompt cache.
- `cost_usd`: the request's cost in US dollars. It is used only when you do not pass `MODEL`; with `MODEL`, pass `0`.
- `latency_ms`: the request's latency in milliseconds.

All token counts and the latency are non-negative integers; `cost_usd` is a
non-negative number.

## Options

| Option | Effect |
| --- | --- |
| `ERROR 0` or `ERROR 1` | `1` (any non-zero value) counts the request as failed. Default `0`. |
| `MODEL model` | Compute the cost from the shared price table (see [LLMSTATS.PRICE](https://docs.hotkv.com/commands/llmstats-price/index.md)) using all the token counts given, instead of `cost_usd`. If the model has no price, the request still counts its tokens, adds nothing to the cost and increments `unpriced_requests`. |
| `CACHEWRITE5M n` | Tokens written to a 5-minute provider cache. |
| `CACHEWRITE1H n` | Tokens written to a 1-hour provider cache. |

Options follow the positional arguments in name and value pairs, in any order.

Providers count tokens differently. Anthropic reports uncached input,
cache-read and cache-write tokens separately, which map straight onto these
arguments. OpenAI's prompt token count includes the cached tokens, so
subtract `cached_tokens` from it before you pass it as `input_tokens` with
`MODEL`.

## Return value

| Case | RESP2 | RESP3 |
| --- | --- | --- |
| Request recorded | Simple string `OK` | Same |

Errors:

- `ERR invalid numeric argument` if a positional count is not a non-negative integer, or `cost_usd` is negative or not a number.
- `ERR invalid ERROR flag`, `ERR invalid CACHEWRITE5M` or `ERR invalid CACHEWRITE1H` if an option value is not a non-negative integer.
- `ERR syntax error` if an option has no value.
- `ERR unknown option` for any other option name.
- `ERR bucket limit reached` if the bucket is new and the server already holds its maximum number of buckets.
- `ERR wrong number of arguments for 'llmstats.record' command` if the argument count is wrong.
- `NOLICENSE llm-stats requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `llm-stats` feature.

## Examples

```
127.0.0.1:6379> LLMSTATS.RECORD model_sonnet5 100000 2000 50000 0 420 MODEL claude-sonnet-5 CACHEWRITE5M 10000
OK
127.0.0.1:6379> LLMSTATS.RECORD self_hosted 1200 300 0 0.0042 95
OK
127.0.0.1:6379> LLMSTATS.RECORD self_hosted 900 0 0 0 30000 ERROR 1
OK
```

The first call is priced from the built-in `claude-sonnet-5` price; the
second records a cost you computed yourself.

## Compatibility

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

## See also

[LLMSTATS.BUCKET](https://docs.hotkv.com/commands/llmstats-bucket/index.md), [LLMSTATS.GET](https://docs.hotkv.com/commands/llmstats-get/index.md), [LLMSTATS.RESET](https://docs.hotkv.com/commands/llmstats-reset/index.md), [LLMSTATS.DROP](https://docs.hotkv.com/commands/llmstats-drop/index.md), [LLMSTATS.LIST](https://docs.hotkv.com/commands/llmstats-list/index.md), [LLMSTATS.PRICE](https://docs.hotkv.com/commands/llmstats-price/index.md), [LLMBUDGET.CONSUME](https://docs.hotkv.com/commands/llmbudget-consume/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)