id: usage-counts
type: concept
owner: justin
component: usage
describes:
  - src/usage.ts
reviewed: 2026-10-13

Usage counts

src/usage.ts keeps one KV key per tool per UTC day in the USAGE namespace:

calls:2026-10-10:convert_units  ->  { "calls": 41, "errors": 3 }

A call counts when it reached the tool, whether the tool succeeded or returned a ToolError. A call rejected by the input schema does not count, and neither does tools/list.

Writes

countCall reads the key, adds one, and writes it back with the counts as both the value and the key's metadata, and a 90 day expiry. It runs inside ctx.waitUntil (see [[http-transport]]), so it never slows a response.

Reads

GET /stats?days=N (1 to 31, default 7) calls readUsage, which lists each day's prefix and takes the counts from the metadata that list() already returns. A day costs one list call, not one get per tool. Days with no calls appear with an empty tools object, so the response always has N entries.

How far to trust it

The counts are close, not exact. Two calls to the same tool in the same moment can both read 41 and both write 42. KV is also eventually consistent: a write can take up to a minute to show in other locations. That is enough to see which tools models use and which ones fail often, and it is the trade [[0003-usage-counts-in-kv]] makes.