# PCACHE.STATS

> Report entries, hits, misses, evictions, memory, lookup latency and savings for a prompt cache namespace.

URL: https://docs.hotkv.com/commands/pcache-stats/

```
PCACHE.STATS namespace
```

- Group: Prompt cache
- Complexity: O(1)
- HotKV Cloud: Performance and Scale plans
- On-Premise: requires the prompt-cache license feature

The prompt cache is an exact-match cache for LLM prompt and response pairs, organised in named namespaces. `PCACHE.STATS` reports counters for one namespace. For a namespace
that does not exist, every counter is zero.

## Return value

The reply is a flat array of alternating field names and values in both RESP2 and RESP3 (it is not sent as a RESP3 map). The fields, in order:

| Field | Type | Meaning |
| --- | --- | --- |
| `entries` | Integer | Entries currently stored. |
| `hits` | Integer | Lookups that found a live entry. |
| `misses` | Integer | Lookups that found nothing or an expired entry. |
| `evictions` | Integer | Entries removed to make room or because they expired. |
| `memory_bytes` | Integer | Approximate memory used by the entries. |
| `hit_rate` | Bulk string | `hits / (hits + misses)`, or `0`. |
| `p50_ns`, `p95_ns`, `p99_ns` | Integer | Lookup latency percentiles in nanoseconds. |
| `cost_saved_usd` | Bulk string | `hits` multiplied by the namespace's `COST_PER_HIT`. |
| `usage_saved_requests` | Integer | Hits on entries that carried usage options. |
| `usage_saved_input_tokens` | Integer | Input tokens those hits did not have to spend. |
| `usage_saved_output_tokens` | Integer | Output tokens those hits did not have to spend. |
| `usage_saved_cache_read_tokens` | Integer | Provider cache-read tokens saved. |
| `usage_saved_cache_write_tokens` | Integer | Provider cache-write tokens saved (5-minute and 1-hour combined). |
| `usage_saved_cost_usd` | Bulk string | Cost saved in US dollars with six decimals, for priced models only. |

The `usage_saved_*` fields only grow for entries stored with the usage
options of [PCACHE.SET](https://docs.hotkv.com/commands/pcache-set/index.md).

Errors:

- `ERR wrong number of arguments for 'pcache.stats' command` if the argument count is wrong.
- `NOLICENSE prompt-cache requires a HotKV license. Contact sales@hotkv.com` if your license does not include the `prompt-cache` feature.

## Examples

```
127.0.0.1:6379> PCACHE.CREATE llm_prompts COST_PER_HIT 0.012
OK
127.0.0.1:6379> PCACHE.SET llm_prompts "Translate: Hello" "Bonjour" MODEL gpt-4o INPUT 20 OUTPUT 3
OK
127.0.0.1:6379> PCACHE.GET llm_prompts "Translate: Hello"
"Bonjour"
127.0.0.1:6379> PCACHE.STATS llm_prompts
 1) "entries"
 2) (integer) 1
 3) "hits"
 4) (integer) 1
 5) "misses"
 6) (integer) 0
 7) "evictions"
 8) (integer) 0
 9) "memory_bytes"
10) (integer) 87
11) "hit_rate"
12) "1"
13) "p50_ns"
14) (integer) 2000
15) "p95_ns"
16) (integer) 2000
17) "p99_ns"
18) (integer) 2000
19) "cost_saved_usd"
20) "0.012"
21) "usage_saved_requests"
22) (integer) 1
23) "usage_saved_input_tokens"
24) (integer) 20
25) "usage_saved_output_tokens"
26) (integer) 3
27) "usage_saved_cache_read_tokens"
28) (integer) 0
29) "usage_saved_cache_write_tokens"
30) (integer) 0
31) "usage_saved_cost_usd"
32) "0.000080"
```

The latency and memory figures depend on your server and data.

## Compatibility

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

## See also

[PCACHE.CREATE](https://docs.hotkv.com/commands/pcache-create/index.md), [PCACHE.SET](https://docs.hotkv.com/commands/pcache-set/index.md), [PCACHE.GET](https://docs.hotkv.com/commands/pcache-get/index.md), [PCACHE.GETEX](https://docs.hotkv.com/commands/pcache-getex/index.md), [PCACHE.DEL](https://docs.hotkv.com/commands/pcache-del/index.md), [PCACHE.FLUSH](https://docs.hotkv.com/commands/pcache-flush/index.md), [PCACHE.DROP](https://docs.hotkv.com/commands/pcache-drop/index.md), [PCACHE.LIST](https://docs.hotkv.com/commands/pcache-list/index.md), [PCACHE.CONFIG](https://docs.hotkv.com/commands/pcache-config/index.md), [LLMSTATS.PRICE](https://docs.hotkv.com/commands/llmstats-price/index.md), [AI features guide](https://docs.hotkv.com/ai-features/index.md)